Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

External orders & POS

Ingest a signed external-order cancellation revision

POST/external-order-ingress/{sourceId}/orders/{externalOrderId}/cancel

Open native orders are canceled atomically using their original admitted or explicitly reviewed legacy source. Submitted orders remain available for explicit operator resolution. Existing command results remain replayable after coverage expires. Hallify HMAC profile external-orders uses HMAC-SHA256. Canonical input: RFC3339 timestamp + "." + key-sorted stable JSON. Send x-hallify-timestamp as rfc3339; timestamps outside ±300 seconds are stale. Send x-hallify-signature as lowercase hexadecimal; comparison is timing-safe. Secret handling: Use the issued base64url text as the UTF-8 signing secret. Accepted Content-Type: application/json. Malformed input: A malformed signature returns 401 Webhook signature is invalid. Stale input: A timestamp outside the 300-second window returns 401 Webhook timestamp is stale. Repeated delivery: Order revision and payload fingerprint semantics control duplicate and conflicting delivery.

Authentication

x-hallify-signature: <HALLIFY_SIGNATURE>

HMAC-SHA256 signature credential. Each operation documents its exact protocol through x-hallify-hmac metadata and the operation description.

Connection guide

Parameters

sourceIdPath · Required

Configured ingestion or integration source selected within the authenticated parent scope.

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

Provider-assigned external order identifier scoped to the authenticated HMAC source.

string
Full definition
{
  "type": "string",
  "example": "example"
}
x-hallify-timestampHeader · Required

rfc3339 timestamp; accepted clock skew is ±300 seconds.

string
Full definition
{
  "type": "string",
  "example": "example"
}

Request body

Required

Monotonic external revision and cancellation reason consumed as the signed cancellation command for the route order identifier.

application/json

ExternalOrderCancelIngressDto
Full definition
{
  "$ref": "#/components/schemas/ExternalOrderCancelIngressDto"
}

Responses

201Returns the recorded external cancellation revision. Native orders beyond the open state retain their operator-resolution workflow.
ExternalOrderIngressCancelResultDto
Full definition
{
  "$ref": "#/components/schemas/ExternalOrderIngressCancelResultDto"
}
Example response · 201 · application/json
{
  "id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
  "status": "example",
  "externalRevision": 1,
  "duplicate": false
}
400External-order source identifier or cancellation payload is invalid
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"
}
401External-order HMAC signature is invalid or stale
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"
}
404External-order source or order was not found
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"
}
409External-order revision or order state conflicts with current state. POS_EXTERNAL_ORDER_ORIGINAL_EVIDENCE_REQUIRED means the original order has neither admitted nor explicitly reviewed legacy continuation evidence and requires source review; current subscription coverage does not replace that evidence.
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"
}
503External-order signing, original-order evidence, command source or replay state is unavailable
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

ExternalOrderCancelIngressDto

Open native orders are canceled atomically.

externalRevisionRequired

Monotonic optimistic-concurrency revision for external order cancel ingress. Accepted values enforce minimum 1.

integer
Full definition
{
  "type": "integer",
  "minimum": 1,
  "description": "Monotonic optimistic-concurrency revision for external order cancel ingress. Accepted values enforce minimum 1.",
  "example": 1
}
reasonRequired

Human-entered reason retained with external order cancel ingress as decision or audit evidence. Accepted values enforce minimum length 3 and maximum length 500.

string
Full definition
{
  "type": "string",
  "minLength": 3,
  "maxLength": 500,
  "description": "Human-entered reason retained with external order cancel ingress as decision or audit evidence. Accepted values enforce minimum length 3 and maximum length 500.",
  "example": "Synthetic example"
}
Full definition
{
  "type": "object",
  "properties": {
    "externalRevision": {
      "type": "integer",
      "minimum": 1,
      "description": "Monotonic optimistic-concurrency revision for external order cancel ingress. Accepted values enforce minimum 1.",
      "example": 1
    },
    "reason": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500,
      "description": "Human-entered reason retained with external order cancel ingress as decision or audit evidence. Accepted values enforce minimum length 3 and maximum length 500.",
      "example": "Synthetic example"
    }
  },
  "required": [
    "externalRevision",
    "reason"
  ],
  "description": "Open native orders are canceled atomically.",
  "example": {
    "externalRevision": 1,
    "reason": "Synthetic example"
  }
}
ExternalOrderIngressCancelResultDto

Returns the recorded cancellation revision and the resulting native-order resolution state.

Full definition
{
  "oneOf": [
    {
      "type": "object",
      "required": [
        "id",
        "status",
        "externalRevision",
        "duplicate"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying external order ingress.",
          "example": "a42073ae-5313-4ace-86d8-86fb33fde1a9"
        },
        "status": {
          "type": "string",
          "description": "Current lifecycle status of external order ingress.",
          "example": "example"
        },
        "externalRevision": {
          "type": "integer",
          "minimum": 0,
          "description": "Monotonic optimistic-concurrency revision for external order ingress. Accepted values enforce minimum 0.",
          "example": 1
        },
        "duplicate": {
          "type": "boolean",
          "enum": [
            false
          ],
          "description": "Allowed duplicate for external order ingress: false.",
          "example": false
        }
      },
      "example": {
        "id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
        "status": "example",
        "externalRevision": 1,
        "duplicate": false
      }
    },
    {
      "type": "object",
      "required": [
        "id",
        "status",
        "duplicate"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying external order ingress.",
          "example": "a7476fce-e842-42a4-896a-c23b0e88b420"
        },
        "status": {
          "type": "string",
          "description": "Current lifecycle status of external order ingress.",
          "example": "example"
        },
        "duplicate": {
          "type": "boolean",
          "enum": [
            true
          ],
          "description": "Allowed duplicate for external order ingress: true.",
          "example": true
        }
      },
      "example": {
        "id": "a7476fce-e842-42a4-896a-c23b0e88b420",
        "status": "example",
        "duplicate": true
      }
    }
  ],
  "description": "Returns the recorded cancellation revision and the resulting native-order resolution state.",
  "example": {
    "id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
    "status": "example",
    "externalRevision": 1,
    "duplicate": false
  }
}
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.