# Create Transaction You can use this call to create a new iDEAL QR transaction. ## Prerequisite Get an `access_token` and use it as 'Bearer' token in your request. Find more details [here](authorization-3). ## Request ```text POST https://api.pay.cm.com/api/v1/paymentmethods/idealqr/v1/transactions ``` ### Request body examples These are only some examples of the request body to create a transaction: ```json Full Request with ReturnURLs { "amountChangeable": { "min": 1, "max": 50000 }, "reference": "20210623130413", "amount": 1200, "currency": "EUR", "purchaseId": "order123", "description": "Order at yourdomain.tld", "expiresAt": "2006-01-02T15:04:05Z", "reusable": false, "size": 200, "language": "nl", "webhooks": [ { "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" ] } ], "returnUrls": { "success": "https://yourdomain.tld/order/payment-success.html", "cancelled": "https://yourdomain.tld/order/payment-cancelled.html", "expired": "https://yourdomain.tld/order/payment-expired.html", "failed": "https://yourdomain.tld/order/payment-failed.html" } } ``` ```json Full Request with ReturnURL { "amountChangeable": { "min": 1, "max": 50000 }, "reference": "20210623130413", "amount": 1200, "currency": "EUR", "purchaseId": "order123", "description": "Order at yourdomain.tld", "expiresAt": "2006-01-02T15:04:05Z", "reusable": false, "size": 200, "language": "nl", "webhooks": [ { "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" ] } ], "returnUrl": "https://yourdomain.tld/order/payment-completed.html" } ``` ```json Minimal Request with ReturnURLs { "reference": "20210623130413", "amount": 1200, "description": "Order at yourdomain.tld", "expiresAt": "2006-01-02T15:04:05Z", "size": 200, "returnUrl": "https://yourdomain.tld/order/payment-completed.html" } ``` "**Full Request with ReturnURLs**" and "**Full Request with ReturnURL**" are examples where all the request parameters are provided. If `returnUrls` is defined then customers will be redirected to a different URL depending on the status of the transaction when the payment process is completed. If `returnUrl` is defined then customers will be redirected to the same URL no matter the status of the transaction when the payment process is completed. "**Minimal Request with ReturnURLs**" is an example of the minimal request to create a transaction. This example, is using `returnUrls`, but you can replace it for `returnUrl` depending on what is better for your use case. ## Parameters | Parameter | Type | Description | Constraints | | :---------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | | reference | String(1...255) | An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload. | | | amount | Int(1...99999999) | Integer representing the amount of the transaction. Denomination in the smallest currency subunit (e.g. eurocents). | | | description | String(1...255) | Description of the transaction. | | | expiresAt | String(RFC3339) | Expiration time. | ISO 8601 date and time. | | size | Int(100...2000) | Determines the size of the image in pixels. (e.g. A size of 200 will produce an image of \~200x200 pixels) | | | returnUrl | String(2000) | Specifies the URL where your customers will be redirected to when the payment process is completed. | Either `returnUrl` or `returnUrls` must be specified, but not both. | | returnUrls | [returnUrls](schemas-2#returnurls) Object | Specifies a URL where your customers will be redirected to (per transaction status) when the payment process is completed. For example, your customers will be redirected to `returnUrls.success` when the status of the transaction changes to `SUCCESS`. | Either `returnUrl` or `returnUrls` must be specified, but not both. | ## Optional parameters | Parameter | Type | Description | Constraints | | :--------------- | :---------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ | | amountChangeable | [amountChangeable](schemas-2#amountchangeable) Object | Contains the minimum and maximum values for the amount of a QR code that your customers can set themselves after scanning the code. | | | language | String(ISO 639-1) | Preferred language of the user interface. | ISO 639-1 language. | | currency | String (ISO 4217) | Currency code. | ISO 4217 currency code. | | purchaseId | String(1...35) | Identification of the order within your system. Ultimately appears on the payment confirmation (statement and confirmation screen). | | | reusable | Boolean | Indicates the QR code's ability to accept multiple successful payments. | | | webhooks | Array of objects | Webhooks enable receiving a web request once a given event occurs. | Find more details [here](webhooks-1). | ## Response ```json { "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d", "amountChangeable": { "min": 1, "max": 50000 }, "reference": "20210623130413", "amount": 1200, "currency": "EUR", "purchaseId": "order123", "description": "Order at yourdomain.tld", "size": 200, "expiresAt": "2006-01-02T15:04:05Z", "reusable": false, "language": "nl", "webhooks": [ { "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" ] } ], "status": "OPEN", "action": { "qrcode": { "id": "213981209381209390821-123", "url": "https://qrbackend.tld/images/213981209381209390821-123.png" } }, "createdAt": "2006-01-02T15:04:05Z", "returnUrls": { "success": "https://yourdomain.tld/order/payment-success.html", "cancelled": "https://yourdomain.tld/order/payment-cancelled.html", "expired": "https://yourdomain.tld/order/payment-expired.html", "failed": "https://yourdomain.tld/order/payment-failed.html" } } ``` ## Parameters [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "h-3": "Constraints", "0-0": "id", "0-1": "String(36)", "0-2": "Transaction unique identifier.", "0-3": "", "1-0": "reference", "1-1": "String(1...255)", "1-2": "An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload.", "1-3": "Specified in the request.", "2-0": "amount", "2-1": "Int(1...99999999)", "2-2": "Integer representing the amount of the checkout. Denomination in the smallest currency subunit (e.g. eurocents).", "2-3": "Specified in the request.", "3-0": "currency", "3-1": "String (ISO 4217)", "3-2": "Currency code.", "3-3": "Specified in the request.", "4-0": "purchaseId", "4-1": "String(1...35)", "4-2": "Identification of the order within your system. Ultimately appears on the payment confirmation (statement and confirmation screen).", "4-3": "Specified in the request.", "5-0": "description", "5-1": "String(1...255)", "5-2": "Description of the transaction.", "5-3": "Specified in the request.", "6-0": "size", "6-1": "Int(100...2000)", "6-2": "Determines the size of the image in pixels. (e.g. A size of 200 will produce an image of ~200x200 pixels)", "6-3": "Specified in the request.", "7-0": "expiresAt", "7-1": "String(RFC3339)", "7-2": "Expiration time.", "7-3": "", "8-0": "status", "8-1": "String", "8-2": "`OPEN` - Transaction has been created. This is the initial status. \n`SUCCESS` - Transaction successfully paid. \n`CANCELLED` - Transaction has been cancelled by your customers. \n`EXPIRED` - Transaction has not succeeded; expired. \n`FAILURE` - Transaction has not succeeded; unknown reason.", "8-3": "", "9-0": "action", "9-1": "[action](schemas-2#action) Object", "9-2": "The next action to be performed by you for this transaction. This includes the URL of the iDEAL QR code image to be shown to your customer.", "9-3": "This parameter is nullable, and it is only available while the transaction is `OPEN`.", "10-0": "createdAt", "10-1": "String(RFC3339)", "10-2": "Creation time.", "10-3": "ISO 8601 date and time.", "11-0": "returnUrl", "11-1": "String(2000)", "11-2": "Specifies the URL where your customers will be redirected to when the payment process is completed.", "11-3": "Specified in the request.", "12-0": "returnUrls", "12-1": "Object", "12-2": "Specifies a URL where your customers will be redirected to (per transaction status) when the payment process is completed. For example, your customers will be redirected to `returnUrls.success` when the status of the transaction changes to `SUCCESS`.", "12-3": "Specified in the request." }, "cols": 4, "rows": 13, "align": [ "left", "left", "left", "left" ] } [/block] ## Optional parameters | Parameter | Type | Description | Constraints | | :--------------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------ | | amountChangeable | Object | Contains the minimum and maximum values for the amount of a QR code that your customers can set themselves after scanning the code. | Specified in the request. | | reusable | Boolean | Indicates the QR code's ability to accept multiple successful payments. | Specified in the request. | | language | String(ISO 639-1) | Preferred language of the user interface. | Specified in the request. | | webhooks | Array of objects | Webhooks enable receiving a web request once a given event occurs. | Specified in the request. | ## Response codes | HTTP status | Description | | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 201 | Successful transaction. | | 4XX | Client error response (See message for details). This response is given when 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). | | 5XX | Server error response (See message for details). |