Payment Failed

This webhook is sent when a payment has failed.

Webhook Structure

string (UUID)

required

Unique identifier for this event

string (ISO 8601)

required

Timestamp of when the event occurred

string

required

The type of event. Value: payment.failed

object

required

The event data containing the details below

Data Fields

string (UUID)

required

Unique identifier of the failed payment

string

required

Payment scheme. Available values: SCT, SCT_INST, INTERNAL

string

required

Payment direction. Available values: INBOUND, OUTBOUND

array

required

List of errors indicating the reason(s) for the failure. Each error contains the fields below.

string

required

Error code indicating the reason for the failure. See Error Codes below.

string

Human-readable description of the error

Error Codes

New error codes may be added in future versions. Consumers should handle unknown codes gracefully.

Code	ISO	Description
`INCORRECT_ACCOUNT_NUMBER`	AC01	Incorrect account number
`CLOSED_ACCOUNT`	AC04	Closed account
`BLOCKED_ACCOUNT`	AC06	Blocked account
`TRANSACTION_FORBIDDEN`	AG01	Transaction forbidden
`INVALID_BANK_OPERATION_CODE`	AG02	Invalid bank operation code
`DUPLICATE_PAYMENT`	AM05	Duplication
`MISSING_CREDITOR_ADDRESS`	BE04	Missing creditor address
`INVALID_BIC`	RC01	Bank identifier incorrect
`END_CUSTOMER_DECEASED`	MD07	End customer deceased
`NOT_SPECIFIED_REASON_CUSTOMER`	MS02	Not specified reason customer generated
`NOT_SPECIFIED_REASON_AGENT`	MS03	Not specified reason agent generated
`MISSING_DEBTOR_ACCOUNT_OR_ID`	RR01	Missing debtor account or identification
`MISSING_DEBTOR_NAME_OR_ADDRESS`	RR02	Missing debtor name or address
`MISSING_CREDITOR_NAME_OR_ADDRESS`	RR03	Missing creditor name or address
`REGULATORY_REASON`	RR04	Regulatory reason
`AML_REJECTED`	RR04	AML check completed with rejection
`AML_FAILED`	RR04	AML check failed to initialize or timed out
`INSUFFICIENT_FUNDS`	—	Insufficient funds on the account
`LEDGER_TRANSACTION_FAILED`	—	Ledger transaction could not be processed
`GATEWAY_REJECTED`	—	Payment rejected by gateway
`INVALID_REQUEST`	—	Invalid payment request
`SYSTEM_ERROR`	—	Internal system error
`OTHER`	—	Unknown error

Request Example

{
  "id": "e1f6a4b3-8c2d-4e7f-b1a9-4d6c0e3f2b5a",
  "time": "2025-01-15T10:30:00Z",
  "type": "payment.failed",
  "data": {
    "paymentId": "019cde3d-c93f-7e6b-da54-6a1b3c4e7f0d",
    "scheme": "SCT",
    "direction": "OUTBOUND",
    "errors": [
      {
        "code": "TRANSACTION_FORBIDDEN",
        "message": "Transaction forbidden (AG01) (via Oversight)"
      }
    ]
  }
}

Last modified on July 20, 2026

⌘I

Getting Started

Parties

Accounts

Account Statements

Payments

Transactions

Transaction Postings

Oversight

Webhooks

Webhook Structure

Data Fields

Error Codes

Request Example

​Webhook Structure

​Data Fields

​Error Codes

​Request Example

Webhook Structure

Data Fields

Error Codes

Request Example