Payment Exception

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:

Marking

The payment is marked as failed.

Notify

A webhook is sent to both participating partners.

Storage

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

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

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.

Getting started

Core Concepts

Guides

Settlement

Simulation

How Exceptions Work

Webhook Subscription

List Exceptions for a Payment

Response

Exception Object Fields

Best Practices

​How Exceptions Work

​Webhook Subscription

​List Exceptions for a Payment

​Response

​Exception Object Fields

​Best Practices

How Exceptions Work

Webhook Subscription

List Exceptions for a Payment

Response

Exception Object Fields

Best Practices