# /paymentmethods/idealqr/v1/transactions

**Reusable** idealQR transactions only have `open` and `expired` statuses.
When a payment for an idealQR transaction is successful, the transaction status `successful` is updated only for non-reusable idealQR transactions, reusable ones will remain `open` until they expire.
* `QR_PAYMENT_CREATED` webhook is triggered on each payment attempt (whether successful, failed, cancelled or expired).
This is useful for both reusable and non-reusable idealQR transactions.
* `FINALSTATUS` webhook is triggered when the transaction expires, or when the payment is successful (only for non-reusable idealQR transactions).
* `STATUS_CHANGE` webhook is triggered when the transaction has any change in status. This is broader than FINALSTATUS

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Payments Gateway",
    "description": "Common payments API",
    "version": "1.23.0"
  },
  "security": [
    {
      "oAuth2ClientCredentials": []
    }
  ],
  "servers": [
    {
      "url": "/api/v1/"
    }
  ],
  "paths": {
    "/paymentmethods/idealqr/v1/transactions": {
      "post": {
        "description": "**Reusable** idealQR transactions only have `open` and `expired` statuses.\nWhen a payment for an idealQR transaction is successful, the transaction status `successful` is updated only for non-reusable idealQR transactions, reusable ones will remain `open` until they expire.\n* `QR_PAYMENT_CREATED` webhook is triggered on each payment attempt (whether successful, failed, cancelled or expired).\nThis is useful for both reusable and non-reusable idealQR transactions.\n* `FINALSTATUS` webhook is triggered when the transaction expires, or when the payment is successful (only for non-reusable idealQR transactions).\n* `STATUS_CHANGE` webhook is triggered when the transaction has any change in status. This is broader than FINALSTATUS\n",
        "tags": [
          "idealqr"
        ],
        "operationId": "createIdealqrTransaction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "type": "object",
                    "required": [
                      "reference",
                      "amount",
                      "description",
                      "expiresAt",
                      "size"
                    ],
                    "properties": {
                      "amountChangeable": {
                        "$ref": "#/components/schemas/AmountChangeable"
                      },
                      "reference": {
                        "$ref": "#/components/schemas/Reference"
                      },
                      "amount": {
                        "$ref": "#/components/schemas/Amount"
                      },
                      "currency": {
                        "$ref": "#/components/schemas/Currency"
                      },
                      "purchaseId": {
                        "description": "Identification of the transaction within the merchant's system. Letters and numbers only.\nUltimately appears on the payment confirmation (statement and confirmation screen).\n",
                        "type": "string",
                        "pattern": "^\\[a-zA-Z0-9]$",
                        "maxLength": 35,
                        "minLength": 1,
                        "example": "order123"
                      },
                      "description": {
                        "description": "Description of the underlying value or reason of the payment.\nUltimately appears on the payment confirmation (statement and confirmation screen).\n",
                        "type": "string",
                        "maxLength": 35,
                        "example": "Order at yourdomain.tld"
                      },
                      "expiresAt": {
                        "$ref": "#/components/schemas/Datetime"
                      },
                      "reusable": {
                        "$ref": "#/components/schemas/Reusable"
                      },
                      "size": {
                        "type": "integer",
                        "minimum": 100,
                        "maximum": 2000,
                        "example": 200
                      },
                      "language": {
                        "$ref": "#/components/schemas/Language"
                      },
                      "webhooks": {
                        "$ref": "#/components/schemas/TransactionWebhooksQR"
                      }
                    }
                  },
                  {
                    "$ref": "#/components/schemas/ReturnUrl"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/IdealqrTransaction"
          },
          "4XX": {
            "$ref": "#/components/responses/UserError"
          },
          "5XX": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "callbacks": {
          "TransactionWebhook": {
            "$ref": "#/components/callbacks/TransactionWebhookQR"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AmountChangeable": {
        "description": "Contains the minimum and maximum values for the amount of a QR code that a consumer can set themselves after scanning the code.",
        "type": "object",
        "nullable": true,
        "properties": {
          "min": {
            "description": "Minimum of the amount. Must be higher than 0",
            "type": "integer",
            "example": 1
          },
          "max": {
            "description": "Maximum of the amount. Must be higher than the minimum and lower than 5000000.",
            "type": "integer",
            "example": 50000
          }
        }
      },
      "ReturnUrl": {
        "oneOf": [
          {
            "required": [
              "returnUrls"
            ],
            "type": "object",
            "properties": {
              "returnUrls": {
                "type": "object",
                "required": [
                  "success",
                  "cancelled",
                  "expired",
                  "failed"
                ],
                "properties": {
                  "success": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-success.html"
                  },
                  "cancelled": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-cancelled.html"
                  },
                  "expired": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-expired.html"
                  },
                  "failed": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-failed.html"
                  }
                }
              }
            }
          },
          {
            "required": [
              "returnUrl"
            ],
            "type": "object",
            "properties": {
              "returnUrl": {
                "type": "string",
                "format": "url",
                "maxLength": 2000,
                "example": "https://yourdomain.tld/order/return?orderID=order123"
              }
            }
          }
        ]
      },
      "Uuid": {
        "description": "Unique identifier",
        "type": "string",
        "format": "uuid",
        "minLength": 36,
        "maxLength": 36,
        "example": "8db1e7fa-ba8a-4189-92fd-67a20217443d"
      },
      "Reference": {
        "description": "Identifier from client. 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,
        "example": 20210623130413,
        "default": ""
      },
      "Datetime": {
        "description": "ISO 8601 date and time",
        "type": "string",
        "format": "date-time",
        "minLength": 20,
        "example": "2006-01-02T15:04:05Z"
      },
      "Reusable": {
        "description": "Indicates the qr code's ability to accept multiple successful payments",
        "type": "boolean",
        "default": false,
        "example": false
      },
      "Amount": {
        "description": "Denomination in the smallest currency subunit, as for example eurocents.",
        "type": "integer",
        "minimum": 1,
        "maximum": 99999999,
        "example": 1200
      },
      "Currency": {
        "description": "ISO 4217 currency code",
        "type": "string",
        "minLength": 3,
        "maxLength": 3,
        "default": "EUR",
        "example": "EUR"
      },
      "Language": {
        "description": "Preferred language of the user interface",
        "type": "string",
        "example": "nl"
      },
      "TransactionWebhooksQR": {
        "description": "Webhooks enable receiving a web request once a given event occurs. \nWe won't do preventive rate-limiting in order to have the highest throughput possible. \nHowever, we will honor 429 (Too-many-requests) responses per callback. \nWe 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": {
          "type": "object",
          "required": [
            "url",
            "events"
          ],
          "properties": {
            "url": {
              "description": "The URL the request must be send to.",
              "type": "string",
              "format": "url",
              "example": "https://yourdomain.tld/webhooks?purchaseId=order123"
            },
            "events": {
              "description": "The events when this URL must be requested.",
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/components/schemas/TransactionWebhookQREvents"
              }
            }
          }
        },
        "example": [
          {
            "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
            "events": [
              "FINALSTATUS"
            ]
          },
          {
            "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
            "events": [
              "STATUS_CHANGE"
            ]
          },
          {
            "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
            "events": [
              "QR_PAYMENT_CREATED"
            ]
          }
        ]
      },
      "TransactionWebhookQREvents": {
        "description": "* `FINALSTATUS` - When the status of the transaction becomes final; it is no longer `OPEN`.\n* `STATUS_CHANGE` - When the status of the transaction changes to any other value.\n* `QR_PAYMENT_CREATED` - When a new payment is created using the qr code.\n",
        "type": "string",
        "enum": [
          "FINALSTATUS",
          "STATUS_CHANGE",
          "QR_PAYMENT_CREATED"
        ],
        "example": "FINALSTATUS"
      },
      "PaymentWebhookQREvents": {
        "description": "Unique identifier of a payment for a idealQR transaction. Only present for `QR_PAYMENT_CREATED` webhook event.",
        "nullable": true,
        "type": "string",
        "format": "uuid",
        "minLength": 36,
        "maxLength": 36,
        "example": "433a3406-3460-4795-b7ed-b5b9ad1aa9bf"
      },
      "Digest": {
        "description": "Digest of whole message body",
        "type": "string",
        "example": "sha-256=OWM5MDc3ODYwNzdjYjE5NjU0Y2NjMDM4MzEyYzMxZTA5MTAzMDBjYWM1Y2I1ODM4NTdlMDU2MzhiMzE1ZDhjNw==",
        "externalDocs": {
          "description": "Instance Digests in HTTP",
          "url": "https://datatracker.ietf.org/doc/html/rfc3230"
        }
      },
      "TransactionStatus": {
        "description": "* `OPEN`       - Payment has been created. This is the initial status.\n* `SUCCESS`    - Payment has succeeded.\n* `CANCELLED`  - Payment has not succeeded; cancelled by the consumer.\n* `EXPIRED`    - Payment has not succeeded; expired.\n* `FAILURE`    - Payment has not succeeded; unknown reason.\n* `AUTHORIZED` - Payment is authorized.\n* `PENDING`    - Payment could not be completed yet; waiting for something.\n* `CHARGEBACK` - Payment chargeback was created.\n",
        "type": "string",
        "enum": [
          "OPEN",
          "SUCCESS",
          "CANCELLED",
          "EXPIRED",
          "FAILURE",
          "AUTHORIZED",
          "PENDING",
          "CHARGEBACK"
        ],
        "example": "OPEN"
      }
    },
    "responses": {
      "IdealqrTransaction": {
        "description": "iDEAL-QR Transaction details",
        "headers": {
          "Digest": {
            "$ref": "#/components/headers/Digest"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "type": "object",
                  "required": [
                    "id",
                    "reference",
                    "amount",
                    "currency",
                    "purchaseId",
                    "description",
                    "size",
                    "expiresAt",
                    "status",
                    "action",
                    "createdAt"
                  ],
                  "properties": {
                    "id": {
                      "$ref": "#/components/schemas/Uuid"
                    },
                    "amountChangeable": {
                      "$ref": "#/components/schemas/AmountChangeable"
                    },
                    "reference": {
                      "$ref": "#/components/schemas/Reference"
                    },
                    "amount": {
                      "$ref": "#/components/schemas/Amount"
                    },
                    "currency": {
                      "$ref": "#/components/schemas/Currency"
                    },
                    "purchaseId": {
                      "type": "string",
                      "example": "order123"
                    },
                    "description": {
                      "type": "string",
                      "example": "Order at yourdomain.tld"
                    },
                    "size": {
                      "type": "integer",
                      "example": 200
                    },
                    "expiresAt": {
                      "$ref": "#/components/schemas/Datetime"
                    },
                    "reusable": {
                      "$ref": "#/components/schemas/Reusable"
                    },
                    "language": {
                      "$ref": "#/components/schemas/Language"
                    },
                    "webhooks": {
                      "$ref": "#/components/schemas/TransactionWebhooksQR"
                    },
                    "status": {
                      "$ref": "#/components/schemas/TransactionStatus"
                    },
                    "action": {
                      "description": "Next action to be performed by merchant (or consumer) to complete the payment.",
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "qrcode": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "description": "ID of the QR Code known by the iDEAL QR Backend of CM.",
                              "type": "string"
                            },
                            "url": {
                              "description": "URL to QR code image to be scanned by consumer to perform the payment.",
                              "type": "string",
                              "format": "url",
                              "example": "https://qrbackend.tld/images/213981209381209390821.png"
                            },
                            "href": {
                              "description": "URL to which the QR code redirects to perform the payment.",
                              "type": "string",
                              "format": "url",
                              "example": "https://payment-processing-platform/pay/b6d53423-f45c-4e2a-93fd-5c43d351e389"
                            }
                          }
                        }
                      }
                    },
                    "createdAt": {
                      "$ref": "#/components/schemas/Datetime"
                    }
                  }
                },
                {
                  "$ref": "#/components/schemas/ReturnUrl"
                }
              ]
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error. This can be caused by an unresponsive backend",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "id",
                "message"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/Uuid"
                },
                "message": {
                  "type": "string",
                  "example": "Service Unavailable"
                }
              }
            }
          }
        }
      },
      "UserError": {
        "description": "The user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized)",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "id",
                "message"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/Uuid"
                },
                "message": {
                  "type": "string",
                  "example": "no authorization methods provided"
                }
              }
            }
          }
        }
      }
    },
    "headers": {
      "Digest": {
        "description": "Digest of whole message body",
        "schema": {
          "$ref": "#/components/schemas/Digest"
        }
      }
    },
    "callbacks": {
      "TransactionWebhookQR": {
        "$request.body#/webhooks/-/url": {
          "post": {
            "parameters": [
              {
                "in": "header",
                "name": "Digest",
                "description": "Digest of whole message body",
                "example": "sha-256=M2ZkM2VlMGFlZDViOGE2ZTQ5ZmFiOTJiMWIxZTljZDliNjQ2MGEwYmFmMThiN2JlZWIxZThkZjk5ZTY1ZjgyNQ==",
                "schema": {
                  "$ref": "#/components/schemas/Digest"
                }
              }
            ],
            "requestBody": {
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "required": [
                      "createdAt",
                      "event",
                      "transaction",
                      "reference"
                    ],
                    "properties": {
                      "createdAt": {
                        "$ref": "#/components/schemas/Datetime"
                      },
                      "event": {
                        "$ref": "#/components/schemas/TransactionWebhookQREvents"
                      },
                      "transaction": {
                        "$ref": "#/components/schemas/Uuid"
                      },
                      "reference": {
                        "$ref": "#/components/schemas/Reference"
                      },
                      "payment": {
                        "$ref": "#/components/schemas/PaymentWebhookQREvents"
                      }
                    }
                  }
                }
              }
            },
            "responses": {
              "2XX": {
                "description": "Webhook successful."
              },
              "default": {
                "description": "Webhook failed. Will be retried several times."
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "oAuth2ClientCredentials": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/api/v1/authorization/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 103,
      "1": 234,
      "2": 76,
      "3": 191,
      "4": 145,
      "5": 198,
      "6": 48,
      "7": 79,
      "8": 46,
      "9": 249,
      "10": 185,
      "11": 249
    }
  }
}
```