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:
1

Marking

The payment is marked as failed.
2

Notify

A webhook is sent to both participating partners.
3

Storage

A full exception object is stored and can be retrieved via the API.
4

Halting

No further progress is made on the payment.

​
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. 
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

{
  "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

FieldTypeDescription
tokenstringUnique identifier for the exception
payment_idstringPayment this exception belongs to
record_typestringType of object that triggered the exception (PaymentSubmission, PaymentAdmission, etc.)
exception_codestringCode representing the type of failure
exception_messagestringHuman-readable explanation
blamestringWhich party is responsible: debtor_party, beneficiary_party, or system
relationships.paymentobjectSnapshot 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.