Skip to main content
This webhook is sent when a payment has failed.

​
Webhook Structure

​
id
string (UUID)
required
Unique identifier for this event
​
time
string (ISO 8601)
required
Timestamp of when the event occurred
​
type
string
required
The type of event. Value: payment.failed
​
data
object
required
The event data containing the details below

​
Data Fields

​
data.paymentId
string (UUID)
required
Unique identifier of the failed payment
​
data.scheme
string
required
Payment scheme. Available values: SCT, SCT_INST
​
data.direction
string
required
Payment direction. Available values: INBOUND, OUTBOUND
​
data.errorCode
string
required
Error code indicating the reason for the failure. See Error Codes below.
​
data.errorMessage
string
required
Human-readable description of the error

​
Error Codes

New error codes may be added in future versions. Consumers should handle unknown codes gracefully.
CodeISODescription
INCORRECT_ACCOUNT_NUMBERAC01Incorrect account number
CLOSED_ACCOUNTAC04Closed account
BLOCKED_ACCOUNTAC06Blocked account
TRANSACTION_FORBIDDENAG01Transaction forbidden
INVALID_BANK_OPERATION_CODEAG02Invalid bank operation code
DUPLICATE_PAYMENTAM05Duplication
MISSING_CREDITOR_ADDRESSBE04Missing creditor address
INVALID_BICRC01Bank identifier incorrect
END_CUSTOMER_DECEASEDMD07End customer deceased
NOT_SPECIFIED_REASON_CUSTOMERMS02Not specified reason customer generated
NOT_SPECIFIED_REASON_AGENTMS03Not specified reason agent generated
MISSING_DEBTOR_ACCOUNT_OR_IDRR01Missing debtor account or identification
MISSING_DEBTOR_NAME_OR_ADDRESSRR02Missing debtor name or address
MISSING_CREDITOR_NAME_OR_ADDRESSRR03Missing creditor name or address
REGULATORY_REASONRR04Regulatory reason
AML_REJECTEDRR04AML check completed with rejection
AML_FAILEDRR04AML 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",
    "errorCode": "TRANSACTION_FORBIDDEN",
    "errorMessage": "Transaction forbidden (AG01) (via Oversight)"
  }
}
Last modified on March 25, 2026