Skip to content

PaymentExceptionEvent ​

Type: schema

Description ​

A payment or refund conflict held for an admin's decision, as the payment.exception.* events carry it: the payment exception without occurrence_count and last_seen_at. A repeat sighting of the same conflict is not a change: it sends no event.

TypeScript Definition ​

typescript
PaymentExceptionEvent: {{
            ulid: string;
            /** Format: date-time */
            created_at: string;
            /** Format: date-time */
            modified_at: string;
            /** @enum {string} */
            exception_domain: "payment" | "refund";
            /** @description Conflict reported by the payment system. Open string; values are not restricted to a closed enum. `duplicate_txn` (domain `payment`): a second transaction charged on a payment the order is already paid by; its money is recorded as a payment of its own (request number `{request_number}-{transaction reference}`, with its `payment.received`), funding no order, and a refund the payment gateway makes of it by itself is booked against it. `duplicate_capture` (domain `payment`): a payment captured after it failed or was superseded, while the order is paid otherwise; its money is recorded under the payment's request number and funds no order. `held_refund` (domain `refund`, `event_name` `ORDER_CANCEL`): a shopper cancelled an order while part of its payment was held for an admin's review; `amount` is what is owed to them, `payment_request_number` the held payment, `reason` names the exceptions holding it, and `remarks` is JSON with the refund due (`refund_mode`, `payment_gateway` and the bank account fields). The refund is made once the hold is released. */
            conflict_type: string;
            reason: string;
            remarks: string | null;
            /** @description Gateway name. Open string; values are not restricted to a closed enum. */
            payment_gateway: string;
            event_name: string | null;
            order_id: number | null;
            order_number: string | null;
            order_payment_id: number | null;
            order_payment_retry_log_id: number | null;
            order_refund_id: number | null;
            payment_log_id: number | null;
            payment_request_number: string | null;
            refund_request_number: string | null;
            payment_reference_number: string | null;
            refund_reference_number: string | null;
            amount: number | null;
            currency: string;
            /** @description Order status snapshot. Open string; values are not restricted to a closed enum. */
            order_status: string | null;
            /** @description Order payment status snapshot. Open string; values are not restricted to a closed enum. */
            order_payment_status: string | null;
            /** @description Retry payment status snapshot. Open string; values are not restricted to a closed enum. */
            retry_log_payment_status: string | null;
            order_to_be_paid: number | null;
            order_payment_amount: number | null;
            /** @enum {string} */
            status: "open" | "refund_initiated" | "resolved" | "dismissed";
            resolved_by: string | null;
            /** Format: date-time */
            resolved_at: string | null;
            /** @description Admin or system resolution action; system actions can include auto_refunded and reconciled. Open string; values are not restricted to a closed enum. */
            resolution_action: string | null;
            resolution_remarks: string | null;
            resolved_order_payment_id: number | null;
            resolved_order_refund_id: number | null;
            /** Format: date-time */
            first_seen_at: string;
            /** @description Actions an admin may take on the exception: `['resolve']` while it is `open`, empty otherwise. */
            allowed_actions: "resolve"[];
        };
        /**
         * PaymentInfo
         * @description Common fields in all types of payments.
         */
}

OpenAPI Schema ​

json
{
  "title": "PaymentExceptionEvent",
  "description": "A payment or refund conflict held for an admin's decision, as the `payment.exception.*` events carry it: the payment exception without `occurrence_count` and `last_seen_at`. A repeat sighting of the same conflict is not a change: it sends no event.",
  "type": "object",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/schemas/PaymentExceptionEvent",
    "description": "API reference for the PaymentExceptionEvent schema"
  },
  "required": [
    "ulid",
    "created_at",
    "modified_at",
    "exception_domain",
    "conflict_type",
    "reason",
    "remarks",
    "payment_gateway",
    "event_name",
    "order_id",
    "order_number",
    "order_payment_id",
    "order_payment_retry_log_id",
    "order_refund_id",
    "payment_log_id",
    "payment_request_number",
    "refund_request_number",
    "payment_reference_number",
    "refund_reference_number",
    "amount",
    "currency",
    "order_status",
    "order_payment_status",
    "retry_log_payment_status",
    "order_to_be_paid",
    "order_payment_amount",
    "status",
    "resolved_by",
    "resolved_at",
    "resolution_action",
    "resolution_remarks",
    "resolved_order_payment_id",
    "resolved_order_refund_id",
    "first_seen_at",
    "allowed_actions"
  ],
  "properties": {
    "ulid": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "exception_domain": {
      "type": "string",
      "enum": [
        "payment",
        "refund"
      ]
    },
    "conflict_type": {
      "description": "Conflict reported by the payment system. Open string; values are not restricted to a closed enum. `duplicate_txn` (domain `payment`): a second transaction charged on a payment the order is already paid by; its money is recorded as a payment of its own (request number `{request_number}-{transaction reference}`, with its `payment.received`), funding no order, and a refund the payment gateway makes of it by itself is booked against it. `duplicate_capture` (domain `payment`): a payment captured after it failed or was superseded, while the order is paid otherwise; its money is recorded under the payment's request number and funds no order. `held_refund` (domain `refund`, `event_name` `ORDER_CANCEL`): a shopper cancelled an order while part of its payment was held for an admin's review; `amount` is what is owed to them, `payment_request_number` the held payment, `reason` names the exceptions holding it, and `remarks` is JSON with the refund due (`refund_mode`, `payment_gateway` and the bank account fields). The refund is made once the hold is released.",
      "type": "string"
    },
    "reason": {
      "type": "string"
    },
    "remarks": {
      "type": [
        "string",
        "null"
      ]
    },
    "payment_gateway": {
      "description": "Gateway name. Open string; values are not restricted to a closed enum.",
      "type": "string"
    },
    "event_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "order_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "order_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "order_payment_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "order_payment_retry_log_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "order_refund_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "payment_log_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "payment_request_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "refund_request_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "payment_reference_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "refund_reference_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "amount": {
      "type": [
        "number",
        "null"
      ]
    },
    "currency": {
      "type": "string"
    },
    "order_status": {
      "description": "Order status snapshot. Open string; values are not restricted to a closed enum.",
      "type": [
        "string",
        "null"
      ]
    },
    "order_payment_status": {
      "description": "Order payment status snapshot. Open string; values are not restricted to a closed enum.",
      "type": [
        "string",
        "null"
      ]
    },
    "retry_log_payment_status": {
      "description": "Retry payment status snapshot. Open string; values are not restricted to a closed enum.",
      "type": [
        "string",
        "null"
      ]
    },
    "order_to_be_paid": {
      "type": [
        "number",
        "null"
      ]
    },
    "order_payment_amount": {
      "type": [
        "number",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "refund_initiated",
        "resolved",
        "dismissed"
      ]
    },
    "resolved_by": {
      "type": [
        "string",
        "null"
      ]
    },
    "resolved_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "resolution_action": {
      "description": "Admin or system resolution action; system actions can include auto_refunded and reconciled. Open string; values are not restricted to a closed enum.",
      "type": [
        "string",
        "null"
      ]
    },
    "resolution_remarks": {
      "type": [
        "string",
        "null"
      ]
    },
    "resolved_order_payment_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "resolved_order_refund_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "first_seen_at": {
      "type": "string",
      "format": "date-time"
    },
    "allowed_actions": {
      "description": "Actions an admin may take on the exception: `['resolve']` while it is `open`, empty otherwise.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "resolve"
        ]
      }
    }
  }
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: