> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.paylias.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Exception

> Sometimes a payment fails for one reason or another. Learn about how to handle exceptions.

Sending and receiving payments with the Paylias Payments API is quick and simple, but sometimes a payment fails for one reason or another. If this happens, the API provides an error message to make it easy to identify the cause of the error.

Exceptions are system-generated records that capture any **abnormality** or **failure** encountered during the lifecycle of a payment. These exceptions can be caused by:

* Invalid or missing data from either the initiating or receiving partner
* Business rule violations within Paylias
* System errors, timeouts, or inconsistencies across parties

Once an exception is raised, **the payment flow is halted**. To resume or retry the payment, a **new payment must be initiated**—exceptions are terminal and unrecoverable for the original request.

## How Exceptions Work

Exceptions can be triggered at any stage, including:

* During payment submission
* While creating or processing a payment admission
* While awaiting task resolution
* Just before transaction finalization

Whenever an exception occurs:

<Steps>
  <Step title="Marking">
    The payment is marked as failed.
  </Step>

  <Step title="Notify">
    A webhook is sent to both participating partners.
  </Step>

  <Step title="Storage">
    A full exception object is stored and can be retrieved via the API.
  </Step>

  <Step title="Halting">
    No further progress is made on the payment.
  </Step>
</Steps>

## Webhook Subscription

To receive real-time notifications about exceptions, subscribe to the `payment_exception:created` event.

Your endpoint will receive a webhook payload whenever a new exception is generated.

### List Exceptions for a Payment

Retrieve all exception objects linked to a specific payment.

```bash theme={null}
curl --request GET \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments/{payment_id}/exceptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>'
```

#### Response

```json expandable theme={null}
{
  "ok": true,
  "data": {
    "count": 1,
    "exceptions": [
      {
        "token": "pexc_cvk3rfk20or8munut4g0",
        "payment_id": "pay_123456789",
        "organization_id": "org_ct239n420or249k5bo90",
        "partner_id": "part_ct23b6420or249k5boag",
        "record_type": "PaymentSubmission",
        "exception_code": "O001",
        "exception_message": "Debtor party payment address is missing",
        "blame": "debtor_party",
        "relationships": {
          "payment": {
            "amount": {
              "currency": "USD",
              "total": "10000"
            },
            "beneficiary_party": {
              "billing": {
                "country": "US"
              },
              "email": "ziyad.parekh@gmail.com",
              "first_name": "Ziyad",
              "last_name": "Parekh",
              "payment_address": "ziyad@safepay-platinum",
              "phone": "+923008277879",
              "type": "Payee_Individual"
            },
            "debtor_party": {
              "billing": {
                "country": "US"
              },
              "email": "johnc@stripe.com",
              "first_name": "John",
              "last_name": "Collison",
              "payment_address": "john@stripe-platinum",
              "phone": "+16462442945",
              "type": "Payer_Individual"
            },
            "device": {},
            "expires_at": 1743276991,
            "initiated_at": 1743273391,
            "location": {},
            "organization_id": "org_ct239n420or249k5bo90",
            "partner_id": "part_ct23b6420or249k5boag",
            "payment_id": "pay_123456789",
            "reference": "INV0001"
          }
        }
      }
    ]
  }
}
```

## Exception Object Fields

| Field                   | Type   | Description                                                                                 |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------- |
| `token`                 | string | Unique identifier for the exception                                                         |
| `payment_id`            | string | Payment this exception belongs to                                                           |
| `record_type`           | string | Type of object that triggered the exception (`PaymentSubmission`, `PaymentAdmission`, etc.) |
| `exception_code`        | string | Code representing the type of failure                                                       |
| `exception_message`     | string | Human-readable explanation                                                                  |
| `blame`                 | string | Which party is responsible: `debtor_party`, `beneficiary_party`, or `system`                |
| `relationships.payment` | object | Snapshot of the original payment payload at the time of exception                           |

## Best Practices

* Always listen for `payment_exception:created` webhooks.
* Show a user-friendly message to customers when a payment fails due to an exception.
* Log and monitor exception codes for debugging and support purposes.
* Automatically retry payments only **after** user confirmation and correcting the root cause.