Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Guest portal

List own retained payment receipts

GET/guest-portal/payment-receipts

Resolves the current Guest Portal session and fresh contact assurance in one consistent read transaction, then lists at most 25 original consumed-consent receipts through exact native birth or QR ownership. Ordinary native management expiry does not erase history. Signed PAYMENT_RECEIPTS cursors bind the guest realm, history revision and readable-proof policy. Original acknowledgements remain separate from stored current funds and application progress. This read performs no provider or native lifecycle action and issues no management or payment capability.

Authentication

x-guest-portal-token: <HALLIFY_GUEST_PORTAL_TOKEN>

Guest-owned portal session token.

Connection guide

Parameters

cursorQuery · Optional

Opaque PAYMENT_RECEIPTS continuation returned by the previous page. It binds the exact guest realm, history revision, readable-proof policy and consumed-consent boundary. Omit it to start a fixed-size page of at most 25 receipts.

string
Full definition
{
  "minLength": 1,
  "maxLength": 2048,
  "type": "string",
  "example": "example"
}

Responses

200A validated page of own retained financial summaries with signed continuation and separately labelled original and current values.

Response headers

Cache-Control

Private receipt responses must not be stored by caches.

string
Full definition
{
  "type": "string",
  "enum": [
    "private, no-store, max-age=0"
  ],
  "example": "private, no-store, max-age=0"
}
GuestPortalPaymentReceiptsPage
Full definition
{
  "$ref": "#/components/schemas/GuestPortalPaymentReceiptsPage"
}
Example response · 200 · application/json
{
  "items": [
    {
      "id": "example-id",
      "acceptedAt": "2026-01-15T12:00:00.000Z",
      "consumedAt": "2026-01-15T12:00:00.000Z",
      "payee": {
        "venueName": "example",
        "legalName": "Example name"
      },
      "purpose": "ORDER_BILL",
      "provider": "STRIPE_CONNECT",
      "mode": "TEST",
      "original": {
        "schema": "hallify.restaurant-payment.command-result",
        "version": 1,
        "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
        "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
        "action": "CREATE_CHECKOUT",
        "state": "PREPARED",
        "currency": "USD",
        "principalAmount": "12.50",
        "tipAmount": "0.00",
        "totalAmount": "12.50"
      },
      "current": {
        "fundsState": "NOT_STARTED",
        "applicationState": "PENDING",
        "applicationBlockedReason": null,
        "checkoutRevision": 1
      }
    }
  ],
  "nextCursor": null,
  "hasMore": true
}
400The payment-receipt cursor is malformed, has an invalid signature or purpose, or exceeds the supported bound.
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"
}
401The current Guest Portal session or subject is unavailable.
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"
}
403The current session requires fresh contact verification before private financial history can be read.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 403 · application/json
{
  "statusCode": 403,
  "error": "errors:http.forbidden",
  "code": "HTTP_FORBIDDEN",
  "message": "errors:http.forbidden",
  "translationKey": "errors:http.forbidden"
}
404The signed cursor belongs to another organization, venue, guest identity or guest profile.
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 guest history revision or readable-proof policy changed; restart payment-receipt pagination.
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"
}
503Required protected-data policy or selected retained financial evidence is unavailable or inconsistent.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 503 · application/json
{
  "statusCode": 503,
  "error": "errors:http.serviceUnavailable",
  "code": "HTTP_SERVICE_UNAVAILABLE",
  "message": "errors:http.serviceUnavailable",
  "translationKey": "errors:http.serviceUnavailable"
}

Schemas

GuestPortalPaymentReceiptsPage

Fixed-size page of at most 25 own retained receipts, ordered by consumedAt descending then receipt id descending. Signed continuation is bound to the current guest realm and history policy.

itemsRequired

Complete validated summaries for this page, preserving the retained financial order.

array
Full definition
{
  "type": "array",
  "maxItems": 25,
  "description": "Complete validated summaries for this page, preserving the retained financial order.",
  "items": {
    "type": "object",
    "description": "Guest-owned retained financial summary with original amounts, frozen payee and separately labelled stored current progress. It contains no management or payment capability and no hosted-checkout redirect.",
    "required": [
      "id",
      "acceptedAt",
      "consumedAt",
      "payee",
      "purpose",
      "provider",
      "mode",
      "original",
      "current"
    ],
    "properties": {
      "id": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,191}$",
        "minLength": 1,
        "maxLength": 191,
        "description": "Immutable consumed-consent receipt identifier used by the payment-receipt cursor boundary.",
        "example": "example-id"
      },
      "acceptedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Original UTC instant when the displayed terms were accepted.",
        "example": "2026-01-15T12:00:00.000Z"
      },
      "consumedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Immutable UTC instant when consent was consumed by the original checkout command; this is the primary descending pagination key.",
        "example": "2026-01-15T12:00:00.000Z"
      },
      "payee": {
        "type": "object",
        "description": "Original payee identity from accepted evidence; current venue or legal labels are not substituted.",
        "required": [
          "venueName",
          "legalName"
        ],
        "properties": {
          "venueName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Payee label frozen in the original accepted consent manifest.",
            "example": "example"
          },
          "legalName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Payee label frozen in the original accepted consent manifest.",
            "example": "Example name"
          }
        },
        "example": {
          "venueName": "example",
          "legalName": "Example name"
        }
      },
      "purpose": {
        "type": "string",
        "enum": [
          "ORDER_BILL",
          "RESERVATION_GUARANTEE"
        ],
        "description": "Original frozen financial purpose of the checkout.",
        "example": "ORDER_BILL"
      },
      "provider": {
        "type": "string",
        "enum": [
          "STRIPE_CONNECT",
          "BOG_PAYMENT_MANAGER",
          "TBC_CHECKOUT"
        ],
        "description": "Original provider selected for this frozen checkout.",
        "example": "STRIPE_CONNECT"
      },
      "mode": {
        "type": "string",
        "enum": [
          "TEST",
          "LIVE"
        ],
        "description": "Original TEST or LIVE mode of the checkout.",
        "example": "TEST"
      },
      "original": {
        "allOf": [
          {
            "$ref": "#/components/schemas/GuestPaymentCommandReceiptDto"
          }
        ],
        "description": "Immutable original checkout command acknowledgement; current payment progress is returned separately.",
        "example": {
          "schema": "hallify.restaurant-payment.command-result",
          "version": 1,
          "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
          "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
          "action": "CREATE_CHECKOUT",
          "state": "PREPARED",
          "currency": "USD",
          "principalAmount": "12.50",
          "tipAmount": "0.00",
          "totalAmount": "12.50"
        }
      },
      "current": {
        "type": "object",
        "description": "Stored current checkout progress, separate from the immutable original acknowledgement. Reading this projection performs no reconciliation or native application.",
        "required": [
          "fundsState",
          "applicationState",
          "applicationBlockedReason",
          "checkoutRevision"
        ],
        "properties": {
          "fundsState": {
            "type": "string",
            "enum": [
              "NOT_STARTED",
              "REQUIRES_ACTION",
              "PROCESSING",
              "AUTHORIZED",
              "CAPTURED",
              "PARTIALLY_REFUNDED",
              "REFUNDED",
              "CANCELED",
              "DECLINED",
              "EXPIRED",
              "UNKNOWN"
            ],
            "description": "Current stored funds state, including later capture, refund, cancellation or unresolved evidence.",
            "example": "NOT_STARTED"
          },
          "applicationState": {
            "type": "string",
            "enum": [
              "PENDING",
              "APPLIED",
              "APPLICATION_BLOCKED",
              "RECONCILIATION_REQUIRED"
            ],
            "description": "Current stored state of native financial application.",
            "example": "PENDING"
          },
          "applicationBlockedReason": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 64,
            "description": "Stored native application reason code, or null without a blocking reason.",
            "example": "Synthetic example"
          },
          "checkoutRevision": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Current stored checkout revision.",
            "example": 1
          }
        },
        "example": {
          "fundsState": "NOT_STARTED",
          "applicationState": "PENDING",
          "applicationBlockedReason": null,
          "checkoutRevision": 1
        }
      }
    },
    "example": {
      "id": "example-id",
      "acceptedAt": "2026-01-15T12:00:00.000Z",
      "consumedAt": "2026-01-15T12:00:00.000Z",
      "payee": {
        "venueName": "example",
        "legalName": "Example name"
      },
      "purpose": "ORDER_BILL",
      "provider": "STRIPE_CONNECT",
      "mode": "TEST",
      "original": {
        "schema": "hallify.restaurant-payment.command-result",
        "version": 1,
        "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
        "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
        "action": "CREATE_CHECKOUT",
        "state": "PREPARED",
        "currency": "USD",
        "principalAmount": "12.50",
        "tipAmount": "0.00",
        "totalAmount": "12.50"
      },
      "current": {
        "fundsState": "NOT_STARTED",
        "applicationState": "PENDING",
        "applicationBlockedReason": null,
        "checkoutRevision": 1
      }
    }
  },
  "example": [
    {
      "id": "example-id",
      "acceptedAt": "2026-01-15T12:00:00.000Z",
      "consumedAt": "2026-01-15T12:00:00.000Z",
      "payee": {
        "venueName": "example",
        "legalName": "Example name"
      },
      "purpose": "ORDER_BILL",
      "provider": "STRIPE_CONNECT",
      "mode": "TEST",
      "original": {
        "schema": "hallify.restaurant-payment.command-result",
        "version": 1,
        "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
        "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
        "action": "CREATE_CHECKOUT",
        "state": "PREPARED",
        "currency": "USD",
        "principalAmount": "12.50",
        "tipAmount": "0.00",
        "totalAmount": "12.50"
      },
      "current": {
        "fundsState": "NOT_STARTED",
        "applicationState": "PENDING",
        "applicationBlockedReason": null,
        "checkoutRevision": 1
      }
    }
  ]
}
nextCursorRequired

Opaque PAYMENT_RECEIPTS continuation for the exact last returned boundary when hasMore is true; null at the end of history.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "minLength": 1,
  "maxLength": 2048,
  "description": "Opaque PAYMENT_RECEIPTS continuation for the exact last returned boundary when hasMore is true; null at the end of history.",
  "example": "example"
}
hasMoreRequired

Another fully validated eligible receipt exists after the returned page.

boolean
Full definition
{
  "type": "boolean",
  "description": "Another fully validated eligible receipt exists after the returned page.",
  "example": true
}
Full definition
{
  "type": "object",
  "description": "Fixed-size page of at most 25 own retained receipts, ordered by consumedAt descending then receipt id descending. Signed continuation is bound to the current guest realm and history policy.",
  "required": [
    "items",
    "nextCursor",
    "hasMore"
  ],
  "properties": {
    "items": {
      "type": "array",
      "maxItems": 25,
      "description": "Complete validated summaries for this page, preserving the retained financial order.",
      "items": {
        "type": "object",
        "description": "Guest-owned retained financial summary with original amounts, frozen payee and separately labelled stored current progress. It contains no management or payment capability and no hosted-checkout redirect.",
        "required": [
          "id",
          "acceptedAt",
          "consumedAt",
          "payee",
          "purpose",
          "provider",
          "mode",
          "original",
          "current"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,191}$",
            "minLength": 1,
            "maxLength": 191,
            "description": "Immutable consumed-consent receipt identifier used by the payment-receipt cursor boundary.",
            "example": "example-id"
          },
          "acceptedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Original UTC instant when the displayed terms were accepted.",
            "example": "2026-01-15T12:00:00.000Z"
          },
          "consumedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Immutable UTC instant when consent was consumed by the original checkout command; this is the primary descending pagination key.",
            "example": "2026-01-15T12:00:00.000Z"
          },
          "payee": {
            "type": "object",
            "description": "Original payee identity from accepted evidence; current venue or legal labels are not substituted.",
            "required": [
              "venueName",
              "legalName"
            ],
            "properties": {
              "venueName": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "description": "Payee label frozen in the original accepted consent manifest.",
                "example": "example"
              },
              "legalName": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "description": "Payee label frozen in the original accepted consent manifest.",
                "example": "Example name"
              }
            },
            "example": {
              "venueName": "example",
              "legalName": "Example name"
            }
          },
          "purpose": {
            "type": "string",
            "enum": [
              "ORDER_BILL",
              "RESERVATION_GUARANTEE"
            ],
            "description": "Original frozen financial purpose of the checkout.",
            "example": "ORDER_BILL"
          },
          "provider": {
            "type": "string",
            "enum": [
              "STRIPE_CONNECT",
              "BOG_PAYMENT_MANAGER",
              "TBC_CHECKOUT"
            ],
            "description": "Original provider selected for this frozen checkout.",
            "example": "STRIPE_CONNECT"
          },
          "mode": {
            "type": "string",
            "enum": [
              "TEST",
              "LIVE"
            ],
            "description": "Original TEST or LIVE mode of the checkout.",
            "example": "TEST"
          },
          "original": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GuestPaymentCommandReceiptDto"
              }
            ],
            "description": "Immutable original checkout command acknowledgement; current payment progress is returned separately.",
            "example": {
              "schema": "hallify.restaurant-payment.command-result",
              "version": 1,
              "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
              "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
              "action": "CREATE_CHECKOUT",
              "state": "PREPARED",
              "currency": "USD",
              "principalAmount": "12.50",
              "tipAmount": "0.00",
              "totalAmount": "12.50"
            }
          },
          "current": {
            "type": "object",
            "description": "Stored current checkout progress, separate from the immutable original acknowledgement. Reading this projection performs no reconciliation or native application.",
            "required": [
              "fundsState",
              "applicationState",
              "applicationBlockedReason",
              "checkoutRevision"
            ],
            "properties": {
              "fundsState": {
                "type": "string",
                "enum": [
                  "NOT_STARTED",
                  "REQUIRES_ACTION",
                  "PROCESSING",
                  "AUTHORIZED",
                  "CAPTURED",
                  "PARTIALLY_REFUNDED",
                  "REFUNDED",
                  "CANCELED",
                  "DECLINED",
                  "EXPIRED",
                  "UNKNOWN"
                ],
                "description": "Current stored funds state, including later capture, refund, cancellation or unresolved evidence.",
                "example": "NOT_STARTED"
              },
              "applicationState": {
                "type": "string",
                "enum": [
                  "PENDING",
                  "APPLIED",
                  "APPLICATION_BLOCKED",
                  "RECONCILIATION_REQUIRED"
                ],
                "description": "Current stored state of native financial application.",
                "example": "PENDING"
              },
              "applicationBlockedReason": {
                "type": "string",
                "nullable": true,
                "minLength": 1,
                "maxLength": 64,
                "description": "Stored native application reason code, or null without a blocking reason.",
                "example": "Synthetic example"
              },
              "checkoutRevision": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2147483647,
                "description": "Current stored checkout revision.",
                "example": 1
              }
            },
            "example": {
              "fundsState": "NOT_STARTED",
              "applicationState": "PENDING",
              "applicationBlockedReason": null,
              "checkoutRevision": 1
            }
          }
        },
        "example": {
          "id": "example-id",
          "acceptedAt": "2026-01-15T12:00:00.000Z",
          "consumedAt": "2026-01-15T12:00:00.000Z",
          "payee": {
            "venueName": "example",
            "legalName": "Example name"
          },
          "purpose": "ORDER_BILL",
          "provider": "STRIPE_CONNECT",
          "mode": "TEST",
          "original": {
            "schema": "hallify.restaurant-payment.command-result",
            "version": 1,
            "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
            "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
            "action": "CREATE_CHECKOUT",
            "state": "PREPARED",
            "currency": "USD",
            "principalAmount": "12.50",
            "tipAmount": "0.00",
            "totalAmount": "12.50"
          },
          "current": {
            "fundsState": "NOT_STARTED",
            "applicationState": "PENDING",
            "applicationBlockedReason": null,
            "checkoutRevision": 1
          }
        }
      },
      "example": [
        {
          "id": "example-id",
          "acceptedAt": "2026-01-15T12:00:00.000Z",
          "consumedAt": "2026-01-15T12:00:00.000Z",
          "payee": {
            "venueName": "example",
            "legalName": "Example name"
          },
          "purpose": "ORDER_BILL",
          "provider": "STRIPE_CONNECT",
          "mode": "TEST",
          "original": {
            "schema": "hallify.restaurant-payment.command-result",
            "version": 1,
            "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
            "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
            "action": "CREATE_CHECKOUT",
            "state": "PREPARED",
            "currency": "USD",
            "principalAmount": "12.50",
            "tipAmount": "0.00",
            "totalAmount": "12.50"
          },
          "current": {
            "fundsState": "NOT_STARTED",
            "applicationState": "PENDING",
            "applicationBlockedReason": null,
            "checkoutRevision": 1
          }
        }
      ]
    },
    "nextCursor": {
      "type": "string",
      "nullable": true,
      "minLength": 1,
      "maxLength": 2048,
      "description": "Opaque PAYMENT_RECEIPTS continuation for the exact last returned boundary when hasMore is true; null at the end of history.",
      "example": "example"
    },
    "hasMore": {
      "type": "boolean",
      "description": "Another fully validated eligible receipt exists after the returned page.",
      "example": true
    }
  },
  "example": {
    "items": [
      {
        "id": "example-id",
        "acceptedAt": "2026-01-15T12:00:00.000Z",
        "consumedAt": "2026-01-15T12:00:00.000Z",
        "payee": {
          "venueName": "example",
          "legalName": "Example name"
        },
        "purpose": "ORDER_BILL",
        "provider": "STRIPE_CONNECT",
        "mode": "TEST",
        "original": {
          "schema": "hallify.restaurant-payment.command-result",
          "version": 1,
          "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
          "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
          "action": "CREATE_CHECKOUT",
          "state": "PREPARED",
          "currency": "USD",
          "principalAmount": "12.50",
          "tipAmount": "0.00",
          "totalAmount": "12.50"
        },
        "current": {
          "fundsState": "NOT_STARTED",
          "applicationState": "PENDING",
          "applicationBlockedReason": null,
          "checkoutRevision": 1
        }
      }
    ],
    "nextCursor": null,
    "hasMore": true
  }
}
GuestPaymentCommandReceiptDto

Immutable first PREPARED acknowledgement of the permanent guest CREATE_CHECKOUT command, preserved across identical replay and original-command recovery.

schemaRequired

Discriminator identifying the versioned original payment-command result document.

string
Full definition
{
  "type": "string",
  "enum": [
    "hallify.restaurant-payment.command-result"
  ],
  "description": "Discriminator identifying the versioned original payment-command result document.",
  "example": "hallify.restaurant-payment.command-result"
}
versionRequired

Command-result schema version retained by this acknowledgement.

integer
Full definition
{
  "type": "integer",
  "enum": [
    1
  ],
  "description": "Command-result schema version retained by this acknowledgement.",
  "example": 1
}
checkoutIdRequired

UUID of the original checkout allocated once for this permanent command.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the original checkout allocated once for this permanent command.",
  "example": "f5ef2bdc-76ae-45b6-851a-399882860529"
}
operationIdRequired

UUID of the original CREATE_CHECKOUT provider operation; replay and recovery preserve this operation identity.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the original CREATE_CHECKOUT provider operation; replay and recovery preserve this operation identity.",
  "example": "44352441-86e0-4a70-8642-d5863bea459a"
}
actionRequired

Original accepted command action; this guest boundary acknowledges CREATE_CHECKOUT.

string
Full definition
{
  "type": "string",
  "enum": [
    "CREATE_CHECKOUT"
  ],
  "description": "Original accepted command action; this guest boundary acknowledges CREATE_CHECKOUT.",
  "example": "CREATE_CHECKOUT"
}
stateRequired

State at the first retained acknowledgement, always PREPARED. Current operation, funds and native application states are returned by the checkout progress operation.

string
Full definition
{
  "type": "string",
  "enum": [
    "PREPARED"
  ],
  "description": "State at the first retained acknowledgement, always PREPARED. Current operation, funds and native application states are returned by the checkout progress operation.",
  "example": "PREPARED"
}
currencyRequired

Currency of the original frozen principal, tip and total amounts.

string
Full definition
{
  "type": "string",
  "enum": [
    "USD",
    "GEL"
  ],
  "description": "Currency of the original frozen principal, tip and total amounts.",
  "example": "USD"
}
principalAmountRequired

Original frozen principal before the separately accepted tip, as a two-decimal string in receipt currency.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Original frozen principal before the separately accepted tip, as a two-decimal string in receipt currency."
}
tipAmountRequired

Original frozen tip accepted with the command, as a nonnegative two-decimal string in receipt currency.

string
Full definition
{
  "type": "string",
  "example": "0.00",
  "description": "Original frozen tip accepted with the command, as a nonnegative two-decimal string in receipt currency."
}
totalAmountRequired

Original sum of frozen principal and accepted tip, as a two-decimal string in receipt currency.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Original sum of frozen principal and accepted tip, as a two-decimal string in receipt currency."
}
Full definition
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "hallify.restaurant-payment.command-result"
      ],
      "description": "Discriminator identifying the versioned original payment-command result document.",
      "example": "hallify.restaurant-payment.command-result"
    },
    "version": {
      "type": "integer",
      "enum": [
        1
      ],
      "description": "Command-result schema version retained by this acknowledgement.",
      "example": 1
    },
    "checkoutId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the original checkout allocated once for this permanent command.",
      "example": "f5ef2bdc-76ae-45b6-851a-399882860529"
    },
    "operationId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the original CREATE_CHECKOUT provider operation; replay and recovery preserve this operation identity.",
      "example": "44352441-86e0-4a70-8642-d5863bea459a"
    },
    "action": {
      "type": "string",
      "enum": [
        "CREATE_CHECKOUT"
      ],
      "description": "Original accepted command action; this guest boundary acknowledges CREATE_CHECKOUT.",
      "example": "CREATE_CHECKOUT"
    },
    "state": {
      "type": "string",
      "enum": [
        "PREPARED"
      ],
      "description": "State at the first retained acknowledgement, always PREPARED. Current operation, funds and native application states are returned by the checkout progress operation.",
      "example": "PREPARED"
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD",
        "GEL"
      ],
      "description": "Currency of the original frozen principal, tip and total amounts.",
      "example": "USD"
    },
    "principalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Original frozen principal before the separately accepted tip, as a two-decimal string in receipt currency."
    },
    "tipAmount": {
      "type": "string",
      "example": "0.00",
      "description": "Original frozen tip accepted with the command, as a nonnegative two-decimal string in receipt currency."
    },
    "totalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Original sum of frozen principal and accepted tip, as a two-decimal string in receipt currency."
    }
  },
  "description": "Immutable first PREPARED acknowledgement of the permanent guest CREATE_CHECKOUT command, preserved across identical replay and original-command recovery.",
  "required": [
    "schema",
    "version",
    "checkoutId",
    "operationId",
    "action",
    "state",
    "currency",
    "principalAmount",
    "tipAmount",
    "totalAmount"
  ],
  "example": {
    "schema": "hallify.restaurant-payment.command-result",
    "version": 1,
    "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
    "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
    "action": "CREATE_CHECKOUT",
    "state": "PREPARED",
    "currency": "USD",
    "principalAmount": "12.50",
    "tipAmount": "0.00",
    "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.