Payment exceptions integration

This feature is for Early Adopter Program (EAP) users only, which is not yet accessible to the general public. Contact Magento Support for assistance.

The payment exceptions feature allows you to manage the most common causes of payment exceptions in the Order Management System (OMS), including:

  • Captures
  • Validate authorizations

Enable payment exceptions

To enable the payment exception functionality toggle the Payment Exceptions option in the System Integrator (SI) Portal—Global settings > Payments > Payment exceptions.

Toggling this option to enable the functionality ensures payment exceptions can be managed in your OMS.

Global settings > Payments > Payment exceptions

Functionality

See SLA configuration for more information about how Service-Level Agreements (SLA) work.

These definitions are enabled and configured in your System Integrator (SI) Portal, which is not yet accessible externally. Contact Magento Support for assistance.

Permissions

After the payment exceptions functionality is enabled in your SI Portal you must also configure the correct permissions per user in the OMS Admin.

The following three permissions are available for users via roles in the OMS Admin:

  • No access (no options enabled)—Provides no access to view or manage payment exceptions.

    No access

  • View access—Users may view the payment exceptions options in the OMS, which is useful if the user has limited access to the OMS and uses it for reviewing orders only.

    View access

  • View and manage access—Provides full access for viewing, reviewing, and managing payment exceptions in the OMS Admin.

    View and manage access

To enable payment exception permissions in the OMS Admin:

  1. Click System > Roles.
  2. Click the username for which you want to enable permissions.
  3. Navigate to the Issues management section.
  4. Click to enable or disable the View Payment Exceptions and View and Manage Payment Exceptions options.

After permissions have been set, you can see payment exceptions options in your Dashboard. See the Operations section in the Dashboard page for more info.

See Permissions for more information about configuring users and roles.

Integration

Payment exceptions actions use specifications to communicate with external payment providers, as noted in the Payment exceptions user guide.

See the following specifications for more information:

Payment operation history timeline

Payment exceptions events, along with order payment history, are displayed in a payment operation history timeline within the Detail view of an order’s payment exception.

The Payment operation history timeline shows the automatic events and manual actions of an order, or the order’s payment exception(s), performed by the user.

To see the Payment operation history timeline:

  1. Click the Payment exceptions tab in the OMS Admin dashboard.
  2. Click Manage payment exceptions.
  3. Click Select, then View Details.
  4. View the timeline in the Payment operation history section to see the history of both manual actions and automatic events.

    Timeline view with manual actions and automatic events

    Timeline view

Manual actions are signified with white dots on the timeline and automatic events are signified with black dots.

Timeline view with manual actions and automatic events

Black dot automatic event

Timeline view with manual actions and automatic events

White dot manual action

See the Actions section of the Payment exceptions user guide for more information on manual actions.

The user must have valid permissions to see the Payment operation history timeline. See the View details section of the Payment exceptions user guide for more information.

Order status

Orders with payment exceptions will be placed in an ON HOLD status with a PENDING_EXCEPTION_REVIEW order status reason until exceptions are resolved.

Manual actions

The following manual actions are available for payment exceptions, as noted in the Payment exceptions user guide:

  • Retry
  • Ignore and close
  • Ignore and proceed

Each time you perform any of these manual actions, a related specification message (varies per event) is sent.

The specifications should return either a success or error communication to the OMS in response.

Retry

The retry actions could trigger a magento.payments.payment_event_exception_management.retry_validation message:

Example of a retry_validation message

{
  "payment_event": {
    "gateway": "string",
    "gateway_account": "string",
    "gateway_key": "string",
    "order_id": "string",
    "operation_reference": "string",
    "sales_channel_id": "string"
  },
  "user": "string"
}

Retry actions could also trigger a magento.payments.payment_event_exception_management.retry_capture message:

Example of a retry_capture message

{
    "payment_event": {
        "gateway": "PAY-BOMB",
        "gateway_account": "BOMB",
        "gateway_key": "Order_xx_35",
        "operation_reference": "168",
        "order_id": "abc123",
        "sales_channel_id": "ST1"
    },
    "user": "xxx"
}

Ignore and close

Ignore and close actions can trigger a magento.payments.payment_event_exception_management.mark_capture_unrecoverable message or a magento.payments.payment_event_exception_management.mark_validation_unrecoverable message.

The external payment provider should return a mark as success in response for either message: magento.payments.payment_event_exception_management.mark_validation_success or magento.payments.payment_event_exception_management.mark_capture_success:

Example of a mark_capture_success message

{
    "payment_event": {
        "gateway": "PAY-BOMB",
        "gateway_account": "BOMB",
        "gateway_key": "Order_xx_35",
        "operation_reference": "168",
        "order_id": "abc123",
        "sales_channel_id": "ST1"
    },
    "user": "xx"
}

Search payment exceptions

You can use specifications to perform a search query to find payment exceptions using magento.payments.payment_event_exception_repository specification.

You can also use specifications to fetch and retrieve payment exceptions by the associated operation_reference using magento.payments.payment_event_exception_repository.search:

Example of a search message

{
  "query": {
    "offset": "integer",
    "size": "integer",
    "criteria": {
      "exp": "string",
      "args": [],
      "value": "string",
      "type": "string"
    },
    "include": [
      "string"
    ],
    "order": {
      "key": "magento.common.order_direction"
    }
  }
}

Find payment exceptions

To fetch and retrieve payment exceptions by its associated operation_reference use magento.payments.payment_event_exception_repository.find:

Example of a find message

{
  "id": "string",
  "event_type": "magento.payments.payment_event_type",
  "event_status": "magento.payments.payment_event_status",
  "operation_reference": "string",
  "sub_type": "magento.payments.payment_event_exception_sub_type",
  "status": "string",
  "start_date": "datetime",
  "created_on": "datetime",
  "authorization_date": "datetime",
  "gateway_key": "string",
  "issued_amount": "float",
  "authorized_amount": "float",
  "captured_amount": "float",
  "currency": "string",
  "method_details": {
    "method": "string",
    "submethod": "string",
    "card": {
      "bin": "string",
      "last_four_digits": "string",
      "expiration_year": "string",
      "expiration_month": "string",
      "authorization_code": "string",
      "avs_response_code": "string",
      "cvv_response_code": "string"
    },
    "bank": {
      "account_holder_name": "string",
      "iban": "string",
      "security_indicator": "integer"
    }
  },
  "order_origin_date": "datetime",
  "order_id": "string",
  "order_status": "string",
  "customer": {
    "first_name": "string",
    "last_name": "string"
  },
  "retry_attempts": "integer"
}