Read the currently collectible native guest bill

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

Responses

200Current collectible native bill, including zero balances where applicable, with authorized item availability and eligible merchant choices.

GuestPaymentBillDto

Full definition

{
  "$ref": "#/components/schemas/GuestPaymentBillDto"
}

Example response · 200 · application/json

{
  "payee": {
    "venueName": "Example name",
    "legalName": "Example name"
  },
  "currency": "USD",
  "collectibleAmount": "12.50",
  "merchantChoices": [
    {
      "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
      "provider": "BOG_PAYMENT_MANAGER",
      "label": "example"
    }
  ],
  "orders": [
    {
      "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
      "revision": 1,
      "collectibleAmount": "12.50",
      "items": [
        {
          "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
          "label": "Example name",
          "availableQuantity": "1.0000",
          "collectibleAmount": "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

GuestPaymentBillDto

Current collectible native bill and eligible merchant choices for payment preparation under the caller's origin-bound guest access.

purposeOptional: Present for a genuine reservation guarantee. Order bill responses keep their existing shape.
string
Full definition
{ "type": "string", "enum": [ "RESERVATION_GUARANTEE" ], "description": "Present for a genuine reservation guarantee. Order bill responses keep their existing shape.", "example": "RESERVATION_GUARANTEE" }
guaranteeOptional: Reservation guarantee review; Orders are empty for this source.
allOf
Full definition
{ "description": "Reservation guarantee review; Orders are empty for this source.", "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: Current server-derived venue and legal payee identity for this native bill; financial review retains its own immutable snapshot.
allOf
Full definition
{ "description": "Current server-derived venue and legal payee identity for this native bill; financial review retains its own immutable snapshot.", "allOf": [ { "$ref": "#/components/schemas/GuestPaymentPayeeDto" } ], "example": { "venueName": "Example name", "legalName": "Example name" } }
currencyRequired: Venue bill currency governing all principal and later tip amounts in this guest payment flow.
string
Full definition
{ "type": "string", "enum": [ "USD", "GEL" ], "description": "Venue bill currency governing all principal and later tip amounts in this guest payment flow.", "example": "USD" }
collectibleAmountRequired: Aggregate collectible principal across the returned native Orders, excluding a new tip, as a two-decimal string; 0.00 means no principal is currently available.
string
Full definition
{ "type": "string", "example": "12.50", "description": "Aggregate collectible principal across the returned native Orders, excluding a new tip, as a two-decimal string; 0.00 means no principal is currently available." }
merchantChoicesRequired: Currently eligible configured provider choices for the collectible Orders, bounded by server selection limits; the list is empty when no principal is collectible.
array
Full definition
{ "description": "Currently eligible configured provider choices for the collectible Orders, bounded by server selection limits; the list is empty when no principal is collectible.", "type": "array", "items": { "$ref": "#/components/schemas/GuestPaymentMerchantChoiceDto" }, "example": [ { "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439", "provider": "BOG_PAYMENT_MANAGER", "label": "example" } ] }
ordersRequired: Canonical current bill projections for native Orders admitted by this payment-purpose scope.
array
Full definition
{ "description": "Canonical current bill projections for native Orders admitted by this payment-purpose scope.", "type": "array", "items": { "$ref": "#/components/schemas/GuestPaymentOrderBillDto" }, "example": [ { "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c", "revision": 1, "collectibleAmount": "12.50", "items": [ { "orderItemId": "48069d23-be97-4039-8099-9db268ddf890", "label": "Example name", "availableQuantity": "1.0000", "collectibleAmount": "12.50" } ] } ] }

Full definition

{
  "type": "object",
  "properties": {
    "purpose": {
      "type": "string",
      "enum": [
        "RESERVATION_GUARANTEE"
      ],
      "description": "Present for a genuine reservation guarantee. Order bill responses keep their existing shape.",
      "example": "RESERVATION_GUARANTEE"
    },
    "guarantee": {
      "description": "Reservation guarantee review; Orders are empty for this source.",
      "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": "Current server-derived venue and legal payee identity for this native bill; financial review retains its own immutable snapshot.",
      "allOf": [
        {
          "$ref": "#/components/schemas/GuestPaymentPayeeDto"
        }
      ],
      "example": {
        "venueName": "Example name",
        "legalName": "Example name"
      }
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD",
        "GEL"
      ],
      "description": "Venue bill currency governing all principal and later tip amounts in this guest payment flow.",
      "example": "USD"
    },
    "collectibleAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Aggregate collectible principal across the returned native Orders, excluding a new tip, as a two-decimal string; 0.00 means no principal is currently available."
    },
    "merchantChoices": {
      "description": "Currently eligible configured provider choices for the collectible Orders, bounded by server selection limits; the list is empty when no principal is collectible.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GuestPaymentMerchantChoiceDto"
      },
      "example": [
        {
          "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
          "provider": "BOG_PAYMENT_MANAGER",
          "label": "example"
        }
      ]
    },
    "orders": {
      "description": "Canonical current bill projections for native Orders admitted by this payment-purpose scope.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GuestPaymentOrderBillDto"
      },
      "example": [
        {
          "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
          "revision": 1,
          "collectibleAmount": "12.50",
          "items": [
            {
              "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
              "label": "Example name",
              "availableQuantity": "1.0000",
              "collectibleAmount": "12.50"
            }
          ]
        }
      ]
    }
  },
  "description": "Current collectible native bill and eligible merchant choices for payment preparation under the caller's origin-bound guest access.",
  "required": [
    "payee",
    "currency",
    "collectibleAmount",
    "merchantChoices",
    "orders"
  ],
  "example": {
    "payee": {
      "venueName": "Example name",
      "legalName": "Example name"
    },
    "currency": "USD",
    "collectibleAmount": "12.50",
    "merchantChoices": [
      {
        "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
        "provider": "BOG_PAYMENT_MANAGER",
        "label": "example"
      }
    ],
    "orders": [
      {
        "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
        "revision": 1,
        "collectibleAmount": "12.50",
        "items": [
          {
            "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
            "label": "Example name",
            "availableQuantity": "1.0000",
            "collectibleAmount": "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"
  }
}

GuestPaymentMerchantChoiceDto

Public merchant-binding choice admitted by current venue configuration and the collectible native Order scope.

merchantBindingIdRequired: UUID of the eligible venue merchant binding to submit when reviewing a payment quote.
string · uuid
Full definition
{ "type": "string", "format": "uuid", "description": "UUID of the eligible venue merchant binding to submit when reviewing a payment quote.", "example": "a9365a46-0f50-4efd-89fb-cd79e20e0439" }
providerRequired: Configured payment provider serving this merchant binding; the current merchant configuration controls its execution mode and capabilities.
string
Full definition
{ "type": "string", "enum": [ "BOG_PAYMENT_MANAGER", "TBC_CHECKOUT", "STRIPE_CONNECT" ], "description": "Configured payment provider serving this merchant binding; the current merchant configuration controls its execution mode and capabilities.", "example": "BOG_PAYMENT_MANAGER" }
labelRequired: Public provider display label for this eligible payment choice.
string
Full definition
{ "type": "string", "description": "Public provider display label for this eligible payment choice.", "example": "example" }

Full definition

{
  "type": "object",
  "properties": {
    "merchantBindingId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the eligible venue merchant binding to submit when reviewing a payment quote.",
      "example": "a9365a46-0f50-4efd-89fb-cd79e20e0439"
    },
    "provider": {
      "type": "string",
      "enum": [
        "BOG_PAYMENT_MANAGER",
        "TBC_CHECKOUT",
        "STRIPE_CONNECT"
      ],
      "description": "Configured payment provider serving this merchant binding; the current merchant configuration controls its execution mode and capabilities.",
      "example": "BOG_PAYMENT_MANAGER"
    },
    "label": {
      "type": "string",
      "description": "Public provider display label for this eligible payment choice.",
      "example": "example"
    }
  },
  "description": "Public merchant-binding choice admitted by current venue configuration and the collectible native Order scope.",
  "required": [
    "merchantBindingId",
    "provider",
    "label"
  ],
  "example": {
    "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
    "provider": "BOG_PAYMENT_MANAGER",
    "label": "example"
  }
}

GuestPaymentOrderBillDto

Current collectible principal, revision and authorized item availability for one native Order, produced by the canonical Orders calculation.

orderIdRequired: UUID of the native Order included in the caller's current payment-purpose source.
string · uuid
Full definition
{ "type": "string", "format": "uuid", "description": "UUID of the native Order included in the caller's current payment-purpose source.", "example": "f3127edf-ce4f-4da7-8be5-81b962024e6c" }
revisionRequired: Native Order revision observed while calculating this bill; subsequent canonical quote preparation revalidates current source revisions.
integer
Full definition
{ "type": "integer", "minimum": 1, "description": "Native Order revision observed while calculating this bill; subsequent canonical quote preparation revalidates current source revisions.", "example": 1 }
collectibleAmountRequired: Current collectible principal for this Order after payments, holds and native allocation limits, excluding a new tip, as a two-decimal string in bill currency.
string
Full definition
{ "type": "string", "example": "12.50", "description": "Current collectible principal for this Order after payments, holds and native allocation limits, excluding a new tip, as a two-decimal string in bill currency." }
itemsRequired: Native item positions permitted for this guest bill, including their remaining collectible quantities and principals.
array
Full definition
{ "description": "Native item positions permitted for this guest bill, including their remaining collectible quantities and principals.", "type": "array", "items": { "$ref": "#/components/schemas/GuestPaymentBillItemDto" }, "example": [ { "orderItemId": "48069d23-be97-4039-8099-9db268ddf890", "label": "Example name", "availableQuantity": "1.0000", "collectibleAmount": "12.50" } ] }

Full definition

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the native Order included in the caller's current payment-purpose source.",
      "example": "f3127edf-ce4f-4da7-8be5-81b962024e6c"
    },
    "revision": {
      "type": "integer",
      "minimum": 1,
      "description": "Native Order revision observed while calculating this bill; subsequent canonical quote preparation revalidates current source revisions.",
      "example": 1
    },
    "collectibleAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Current collectible principal for this Order after payments, holds and native allocation limits, excluding a new tip, as a two-decimal string in bill currency."
    },
    "items": {
      "description": "Native item positions permitted for this guest bill, including their remaining collectible quantities and principals.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GuestPaymentBillItemDto"
      },
      "example": [
        {
          "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
          "label": "Example name",
          "availableQuantity": "1.0000",
          "collectibleAmount": "12.50"
        }
      ]
    }
  },
  "description": "Current collectible principal, revision and authorized item availability for one native Order, produced by the canonical Orders calculation.",
  "required": [
    "orderId",
    "revision",
    "collectibleAmount",
    "items"
  ],
  "example": {
    "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
    "revision": 1,
    "collectibleAmount": "12.50",
    "items": [
      {
        "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
        "label": "Example name",
        "availableQuantity": "1.0000",
        "collectibleAmount": "12.50"
      }
    ]
  }
}

GuestPaymentBillItemDto

Authorized native bill position with its captured name, remaining quantity and collectible principal after canonical payment and hold calculations.

orderItemIdRequired: UUID of the native Order item available within the enclosing Order and current guest allocation scope.
string · uuid
Full definition
{ "type": "string", "format": "uuid", "description": "UUID of the native Order item available within the enclosing Order and current guest allocation scope.", "example": "48069d23-be97-4039-8099-9db268ddf890" }
labelRequired: Name snapshot captured on the native Order item and shown with this bill position.
string
Full definition
{ "type": "string", "description": "Name snapshot captured on the native Order item and shown with this bill position.", "example": "Example name" }
availableQuantityRequired: Remaining item quantity collectible under the current native allocation after prior payments and active holds, as a four-decimal string; zero is represented as 0.0000.
string
Full definition
{ "type": "string", "example": "1.0000", "description": "Remaining item quantity collectible under the current native allocation after prior payments and active holds, as a four-decimal string; zero is represented as 0.0000." }
collectibleAmountRequired: Collectible principal for this available item portion in bill currency, excluding any new tip, as a two-decimal string; it can be 0.00.
string
Full definition
{ "type": "string", "example": "12.50", "description": "Collectible principal for this available item portion in bill currency, excluding any new tip, as a two-decimal string; it can be 0.00." }

Full definition

{
  "type": "object",
  "properties": {
    "orderItemId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the native Order item available within the enclosing Order and current guest allocation scope.",
      "example": "48069d23-be97-4039-8099-9db268ddf890"
    },
    "label": {
      "type": "string",
      "description": "Name snapshot captured on the native Order item and shown with this bill position.",
      "example": "Example name"
    },
    "availableQuantity": {
      "type": "string",
      "example": "1.0000",
      "description": "Remaining item quantity collectible under the current native allocation after prior payments and active holds, as a four-decimal string; zero is represented as 0.0000."
    },
    "collectibleAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Collectible principal for this available item portion in bill currency, excluding any new tip, as a two-decimal string; it can be 0.00."
    }
  },
  "description": "Authorized native bill position with its captured name, remaining quantity and collectible principal after canonical payment and hold calculations.",
  "required": [
    "orderItemId",
    "label",
    "availableQuantity",
    "collectibleAmount"
  ],
  "example": {
    "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
    "label": "Example name",
    "availableQuantity": "1.0000",
    "collectibleAmount": "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"
}