{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/cm-com/main/json-schema/cm-com-ideal-transaction-schema.json",
  "title": "IdealTransaction",
  "x-generated": "2026-10-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cm-com-payments-online-payments-v1-27-22-openapi.yml#/components/schemas/IdealTransaction",
  "allOf": [
    {
      "$ref": "#/$defs/Transaction"
    },
    {
      "type": "object",
      "required": [
        "purchaseId",
        "action",
        "idealTransactionId",
        "status"
      ],
      "properties": {
        "description": {
          "$ref": "#/$defs/IDEALDescription"
        },
        "status": {
          "description": "The status of the transaction.\n\n**Note:** `AUTHORIZED` is a transient, non-final status that should not occur for iDEAL, since iDEAL is an instant payment method with no separate authorization step. In rare cases, it may briefly be observed before the status resolves to its final value. It should not be relied upon and does not indicate a final outcome.",
          "oneOf": [
            {
              "$ref": "#/$defs/StatusOpen"
            },
            {
              "$ref": "#/$defs/StatusSuccess"
            },
            {
              "$ref": "#/$defs/StatusCancelled"
            },
            {
              "$ref": "#/$defs/StatusExpired"
            },
            {
              "$ref": "#/$defs/StatusFailure"
            },
            {
              "$ref": "#/$defs/StatusAuthorized"
            }
          ]
        },
        "purchaseId": {
          "$ref": "#/$defs/PurchaseID"
        },
        "action": {
          "type": "object",
          "description": "Next action to be performed by merchant (or consumer) to complete the payment.",
          "properties": {
            "redirect": {
              "$ref": "#/$defs/RedirectAction"
            }
          }
        },
        "issuer": {
          "$ref": "#/$defs/BIC"
        },
        "requestUserToken": {
          "$ref": "#/$defs/IdealPayFastRequestUserToken"
        },
        "expectedDebtor": {
          "$ref": "#/$defs/IdealPayFastExpectedDebtor"
        },
        "notificationResult": {
          "type": "string",
          "format": "enum",
          "enum": [
            "PUSH_SENT_SHOW_WAITING_SCREEN",
            "REDIRECT"
          ],
          "description": "The value `PUSH_SENT_SHOW_WAITING_SCREEN` indicates the issuer attempted to send the notification, and the Merchant should show a \"waiting for notification\"-screen to the Consumer. The value `REDIRECT` indicates the Consumer should be redirected to the `checkoutUrl` as with the normal iDEAL flow.\n\nThis field is only returned when the Pay Fast flow was initiated using the `expectedDebtor`-field."
        },
        "consumer": {
          "$ref": "#/$defs/IdealConsumer"
        },
        "idealTransactionId": {
          "$ref": "#/$defs/IdealTransactionId"
        }
      }
    }
  ],
  "$defs": {
    "Amount": {
      "description": "Denomination in the smallest currency subunit, as for example euro cents.",
      "type": "integer",
      "minimum": 1,
      "maximum": 99999999
    },
    "BIC": {
      "description": "Bank Identification Code",
      "deprecated": true,
      "type": "string",
      "minLength": 8,
      "maxLength": 11
    },
    "BaseWebhook": {
      "type": "object",
      "description": "A single webhook object consists out of an URL to which we need to send the occurred event together with the event that needs to trigger the webhook call.",
      "required": [
        "url",
        "events"
      ],
      "properties": {
        "url": {
          "description": "The URL the request must be send to.",
          "type": "string",
          "format": "url"
        },
        "events": {
          "description": "Type of events that will trigger a webhook.",
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        }
      }
    },
    "Currency": {
      "description": "ISO 4217 currency code.",
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "default": "EUR"
    },
    "Datetime": {
      "type": "string",
      "format": "date-time",
      "minLength": 20,
      "description": "ISO 8601 date and time."
    },
    "Description": {
      "description": "Description of the underlying value or reason of the payment.",
      "type": "string",
      "maxLength": 255
    },
    "FinalStatusEvent": {
      "description": "* `FINALSTATUS` - This value is deprecated and shouldn't be used anymore. Use `STATUS_CHANGE` instead.\n",
      "type": "string",
      "enum": [
        "FINALSTATUS"
      ]
    },
    "IDEALDescription": {
      "maxLength": 35,
      "description": "Description of the underlying value or reason of the payment.\n\nUltimately appears on the payment statement and confirmation screen.\n"
    },
    "IdealAddress": {
      "type": "object",
      "title": "Address",
      "properties": {
        "firstName": {
          "type": "string",
          "description": "The first name of the consumer",
          "minLength": 1
        },
        "lastName": {
          "type": "string",
          "description": "The last name of the consumer",
          "minLength": 1
        },
        "companyName": {
          "type": "string",
          "description": "The company name of the consumer",
          "minLength": 1
        },
        "postalCode": {
          "type": "string",
          "description": "The postal code of the address without spaces",
          "minLength": 1
        },
        "houseNumber": {
          "type": "string",
          "description": "The house number of the address",
          "minLength": 1
        },
        "addition": {
          "type": "string",
          "description": "The addition of the address",
          "minLength": 1
        },
        "street": {
          "type": "string",
          "description": "The street of the address",
          "minLength": 1
        },
        "city": {
          "type": "string",
          "description": "The city of the address",
          "minLength": 1
        },
        "countryName": {
          "type": "string",
          "description": "Name of the country",
          "minLength": 1
        }
      }
    },
    "IdealConsumer": {
      "description": "contains the Name and IBAN that were used by the consumer that completed the payment. This field is null until the payment is completed.",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the consumer",
          "type": "string"
        },
        "bic": {
          "$ref": "#/$defs/BIC"
        },
        "iban": {
          "description": "IBAN of the consumer",
          "type": "string"
        },
        "checkoutDetails": {
          "description": "The checkout details defined by the consumer before completing the transaction.\n\nBy default, the invoice address will be the same as the shipping address unless it is explicitly changed by the\nconsumer.\n\nThis field is only available if the transaction status is `SUCCESS` and checkout data was requested.",
          "type": "object",
          "properties": {
            "contactDetails": {
              "type": "object",
              "title": "DebtorContactDetails",
              "properties": {
                "firstName": {
                  "type": "string",
                  "description": "The first name of the consumer (can be different from the first name in the contact details)",
                  "minLength": 1
                },
                "lastName": {
                  "type": "string",
                  "description": "The last name of the consumer (can be different from the last name in the contact details)",
                  "minLength": 1
                },
                "phoneNumber": {
                  "type": "string",
                  "description": "The phone number of the consumer in E.164 format",
                  "pattern": "^\\+[1-9][0-9]{1,14}$"
                },
                "email": {
                  "type": "string",
                  "description": "The e-mail address of the consumer",
                  "format": "email",
                  "minLength": 1
                }
              }
            },
            "shippingAddress": {
              "$ref": "#/$defs/IdealAddress"
            },
            "invoiceAddress": {
              "$ref": "#/$defs/IdealAddress"
            }
          }
        }
      }
    },
    "IdealPayFastExpectedDebtor": {
      "type": "object",
      "description": "If the Merchant is in possession of a User Token, obtained through a previous transaction, and the Consumer has indicated that he wants to reuse the bank account that was displayed after retrieving it from the `getDebtorPreferences`-endpoint, the User Token and browsers user-agent can be provided to enable the enhanced flow.\n\nThe Consumer for which a User Token is used MUST hold an account with the merchant. The Merchant MUST only use the iDEAL User Token that was received in the last transaction for the Consumer.",
      "required": [
        "userToken"
      ],
      "properties": {
        "userToken": {
          "$ref": "#/$defs/IdealPayFastUserToken"
        },
        "userAgent": {
          "type": "string",
          "description": "The User-Agent contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor, or software version of the requesting software user agent.",
          "minLength": 0,
          "maxLength": 500
        }
      }
    },
    "IdealPayFastRequestUserToken": {
      "description": "Requests a User Token for future Pay Fast transactions with the same Consumer.\n\nWhen enabled and the Consumer consents, a User Token will be generated that enables push notifications in future transactions.\n\nOnly request User Tokens for Consumers who have established accounts with your service and can be reliably identified on return visits.",
      "type": "boolean",
      "default": false
    },
    "IdealPayFastUserToken": {
      "description": "iDEAL Pay Fast User Token as generated by iDEAL, which is received in the response of a Create iDEAL Transaction when the field `\"requestUserToken\"` is set to `true`.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "IdealTransactionId": {
      "description": "The 16-digit transaction ID within the iDEAL scheme as known by the acquirer and issuing bank, and\nused in the credit transfer. The value can have leading zeros.\nThis value is `null` if the status `FAILURE`.",
      "type": [
        "string",
        "null"
      ],
      "minLength": 16,
      "maxLength": 16
    },
    "Language": {
      "description": "Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).",
      "type": "string",
      "default": "nl",
      "minLength": 2,
      "maxLength": 2
    },
    "PurchaseID": {
      "description": "Unique identification of the order within the Merchant's system. This value\nappears on the bank statement of the Consumer.\n\nThe purchaseID can only contain letters and numbers.",
      "type": "string",
      "minLength": 1,
      "maxLength": 35,
      "pattern": "^[A-Za-z0-9]{1,35}$"
    },
    "RedirectAction": {
      "description": "URL where consumer should be redirected to by the merchant to perform the payment.",
      "type": "object",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "description": "URL where consumer should be redirected to by the merchant to perform the payment.",
          "type": "string",
          "format": "url"
        }
      }
    },
    "Reference": {
      "description": "The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "RefundStatusEvent": {
      "description": "* `REFUND_STATUS` - Triggered when a transaction receives an update on one of its requested refunds.\n",
      "type": "string",
      "enum": [
        "REFUND_STATUS"
      ]
    },
    "Refunds": {
      "description": "Details of refunds for a transaction",
      "type": "object",
      "required": [
        "refundedAmount",
        "refundedPendingAmount"
      ],
      "properties": {
        "refundedAmount": {
          "description": "Amount in the smallest currency subunit, as for example euro cents, that has already been refunded.",
          "type": "integer",
          "minimum": 0,
          "maximum": 99999999
        },
        "refundedPendingAmount": {
          "description": "Amount in the smallest currency subunit, as for example euro cents, that has been requested to be refunded.",
          "type": "integer",
          "minimum": 1,
          "maximum": 99999999
        }
      }
    },
    "ReturnURLOneOf": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "returnUrls"
          ],
          "properties": {
            "returnUrls": {
              "$ref": "#/$defs/ReturnUrls"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "returnUrl"
          ],
          "properties": {
            "returnUrl": {
              "$ref": "#/$defs/ReturnUrl"
            }
          }
        }
      ]
    },
    "ReturnUrl": {
      "description": "URL where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.\n\nWith this implementation you are responsible to fetch the payment status and incorporated into your site.",
      "type": "string",
      "format": "url",
      "maxLength": 2000
    },
    "ReturnUrls": {
      "type": "object",
      "description": "URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.\n\nWith this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.",
      "required": [
        "success",
        "cancelled",
        "expired",
        "failed"
      ],
      "properties": {
        "success": {
          "type": "string",
          "format": "url",
          "maxLength": 2000
        },
        "cancelled": {
          "type": "string",
          "format": "url",
          "maxLength": 2000
        },
        "expired": {
          "type": "string",
          "format": "url",
          "maxLength": 2000
        },
        "failed": {
          "type": "string",
          "format": "url",
          "maxLength": 2000
        }
      }
    },
    "StatusAuthorized": {
      "description": "The transaction has been authorized.",
      "type": "string",
      "format": "enum",
      "enum": [
        "AUTHORIZED"
      ]
    },
    "StatusCancelled": {
      "description": "The transaction has been cancelled by the consumer.",
      "type": "string",
      "format": "enum",
      "enum": [
        "CANCELLED"
      ]
    },
    "StatusChangeEvent": {
      "description": "* `STATUS_CHANGE` - Triggered when the status of a transaction changes.\n",
      "type": "string",
      "enum": [
        "STATUS_CHANGE"
      ]
    },
    "StatusExpired": {
      "description": "The transaction has expired.",
      "type": "string",
      "format": "enum",
      "enum": [
        "EXPIRED"
      ]
    },
    "StatusFailure": {
      "description": "The transaction has failed.",
      "type": "string",
      "format": "enum",
      "enum": [
        "FAILURE"
      ]
    },
    "StatusOpen": {
      "description": "The transaction is open and can be paid.",
      "type": "string",
      "format": "enum",
      "enum": [
        "OPEN"
      ]
    },
    "StatusSuccess": {
      "description": "The transaction has been successfully paid.",
      "type": "string",
      "format": "enum",
      "enum": [
        "SUCCESS"
      ]
    },
    "Transaction": {
      "allOf": [
        {
          "$ref": "#/$defs/TransactionWithoutOrderId"
        },
        {
          "type": "object",
          "required": [
            "orderId"
          ],
          "properties": {
            "orderId": {
              "allOf": [
                {
                  "deprecated": true
                },
                {
                  "$ref": "#/$defs/Uuid"
                }
              ]
            }
          }
        }
      ]
    },
    "TransactionId": {
      "description": "ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.",
      "type": "string",
      "format": "uuid",
      "minLength": 36,
      "maxLength": 36
    },
    "TransactionWebhook": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseWebhook"
        },
        {
          "type": "object",
          "properties": {
            "events": {
              "items": {
                "description": "* `STATUS_CHANGE` - Triggered when the status of a transaction changes.\n* `REFUND_STATUS` - Triggered when a transaction receives an update on one of its requested refunds.\n* `FINALSTATUS` - This value is deprecated and shouldn't be used anymore. Use `STATUS_CHANGE` instead.\n",
                "oneOf": [
                  {
                    "$ref": "#/$defs/StatusChangeEvent"
                  },
                  {
                    "$ref": "#/$defs/RefundStatusEvent"
                  },
                  {
                    "$ref": "#/$defs/FinalStatusEvent"
                  }
                ]
              }
            }
          }
        }
      ]
    },
    "TransactionWebhooks": {
      "description": "Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.\n",
      "type": "array",
      "items": {
        "$ref": "#/$defs/TransactionWebhook"
      }
    },
    "TransactionWithoutOrderId": {
      "allOf": [
        {
          "$ref": "#/$defs/TransactionWithoutOrderIdLanguageRefundsAndExpiresAt"
        },
        {
          "type": "object",
          "required": [
            "language",
            "expiresAt"
          ],
          "properties": {
            "language": {
              "$ref": "#/$defs/Language"
            },
            "expiresAt": {
              "$ref": "#/$defs/Datetime",
              "description": "ISO 8601 date and time. If a transaction is not finalized before this time the status becomes **EXPIRED**."
            },
            "refunds": {
              "$ref": "#/$defs/Refunds"
            }
          }
        }
      ]
    },
    "TransactionWithoutOrderIdLanguageRefundsAndExpiresAt": {
      "allOf": [
        {
          "$ref": "#/$defs/TransactionWithoutOrderIdLanguageRefundsCreatedAtAndExpiresAt"
        },
        {
          "type": "object",
          "required": [
            "createdAt"
          ],
          "properties": {
            "createdAt": {
              "$ref": "#/$defs/Datetime",
              "description": "ISO 8601 date and time when the transaction was created."
            }
          }
        }
      ]
    },
    "TransactionWithoutOrderIdLanguageRefundsCreatedAtAndExpiresAt": {
      "allOf": [
        {
          "$ref": "#/$defs/ReturnURLOneOf"
        },
        {
          "type": "object",
          "required": [
            "id",
            "reference",
            "amount",
            "currency",
            "status",
            "description"
          ],
          "properties": {
            "id": {
              "$ref": "#/$defs/TransactionId"
            },
            "reference": {
              "$ref": "#/$defs/Reference"
            },
            "amount": {
              "$ref": "#/$defs/Amount"
            },
            "currency": {
              "$ref": "#/$defs/Currency"
            },
            "webhooks": {
              "$ref": "#/$defs/TransactionWebhooks"
            },
            "description": {
              "$ref": "#/$defs/Description"
            }
          }
        }
      ]
    },
    "Uuid": {
      "description": "Unique identifier",
      "type": "string",
      "format": "uuid",
      "minLength": 36,
      "maxLength": 36
    }
  }
}