# Create Transactions in bulk You can use this call to create several iDEAL QR transactions in 1 bulk request. ## 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/bulk ``` ```json Create using defaults { "defaults": { "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" } }, "qrcodes": [ {}, {}, {} ] } ``` ```json Create using only QR code values { "qrcodes": [ { "amountChangeable": { "min": 1, "max": 50000 }, "reference": "20210623130413", "amount": 1200, "currency": "EUR", "purchaseId": "order123", "description": "Order at yourdomain.tld", "expiresAt": "2024-07-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" } }, { "amountChangeable": { "min": 1, "max": 50000 }, "reference": "5555", "amount": 500, "currency": "EUR", "purchaseId": "order9876", "description": "Order at yourdomain.tld", "expiresAt": "2024-07-02T15:04:05Z", "reusable": false, "size": 200, "language": "nl", "webhooks": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order9876", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order9876", "events": [ "STATUS_CHANGE" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order9876", "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 Create using both defaults and overwritten QR code values { "defaults": { "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" } }, "qrcodes": [ {}, {}, { "returnUrl": "https://otherdomain.tld/order/return?orderID=order123", "reference": "5567", "amount": 55 }, { "returnUrl": "https://otherdomain.tld/order/return?orderID=order123", "reference": "12344", "webhooks": [ { "url": "https://otherdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] } ] } ] } ``` If you want to create several similar QR codes then you can use something like "**Create using defaults**" which is an example where we want to create 3 QR codes and all of them following the values defined as `defaults`. If you want to create several different QR codes then you could use something like "**Create using only QR code values**" which is an example where `defaults` is not defined, and instead 2 specific `qrcodes` have been defined separately. "**Create using both defaults and overwritten QR code values**" is an example where we want to create 4 QR codes: * 2 QR codes following the `defaults`. * 1 QR code using a `returnUrl`, and different values for `reference` and `amount` . * 1 QR code using using a `returnUrl`, a different value for `reference`, and 1 webhook instead of the 3 defined in the `defaults`. ## Parameters | Parameter | Type | Description | Constraints | | :-------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------- | | qrcodes | Array of [requestedQRCodeInBulk](schemas-2#requestedQRCodeInBulk) objects | This is an array of QR codes you want to create in bulk. If a value is specified in both `qrcodes` and `defaults`, the one defined in `qrcodes` will be used. | There is a maximun of 100 objects in 1 request. | ## Optional parameters | Parameter | Type | Description | Constraints | | :-------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :---------- | | defaults | [defaultsForBulkRequest](schemas-2#defaultsForBulkRequest) Object | The default values that will be used for the creation of the QR codes specified in `qrcodes`. | | ## Response ```json Error response example { "error": { "id": "709d2be7-62e1-4cd6-a0f0-80b19209acaf", "message": "Invalid request message" } } ``` ```json Response with QR codes and errors { "qrcodes": [ { "created": true, "transaction": { "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d", "action": { "qrcode": { "id": "string", "url": "https://qrbackend.tld/images/213981209381209390821.png" } } } }, { "created": false, "error": { "id": "51365d8a-d3c1-4c5f-9556-e8d7ff383eee", "message": "Invalid request message" } } ] } ``` ```json Response with only QR codes errors { "qrcodes": [ { "created": false, "error": { "id": "3676573a-8156-43a7-85d5-bc51da008e7d", "message": "Invalid value for Expires: invalid datetime; expiration should be at least 1 minutes in the future" } }, { "created": false, "error": { "id": "beb2e9d9-d794-4386-a5df-69ff701df99e", "message": "Invalid value for Expires: invalid datetime; expiration should be at least 1 minutes in the future" } }, { "created": false, "error": { "id": "f596b9a4-8484-4ae0-a877-fb60e349de5e", "message": "Invalid value for Expires: invalid datetime; expiration should be at least 1 minutes in the future" } } ] } ``` Create iDEAL QR transactions in bulk can give 2 types of response: It is either a **Bulk error response** or a **Bulk `qrcodes` response**. ### Bulk error response This is a response retrieved when an error has been found before even parsing the QR codes in the request. "**Error response example**" is an example of a **Bulk error response**. For this specific example, the response status code is 400. ### Parameters | Parameter | Type | Description | Constraints | | :-------- | :------------------------------ | :---------------------- | :---------- | | error | [error](schemas-2#error) Object | Includes error details. | | ### Bulk `qrcodes` response This is a response retrieved when the request has been successfully parsed and the `qrcodes` in the request have been processed. This does not mean that all the QR codes have been created. In fact, the response will contain the details of the successfully created QR codes and the error details for those that could not be created. "**Response with QR codes and errors**" is an example of a **Bulk `qrcodes` response**. For this specific example the response status code will be 200 since it contains at least one successfully created QR code. "**Response with only QR codes errors**" is another example of a **Bulk `qrcodes` response**. For this specific example the response status code will be 400 since none of them could be created and all the errors are related to a client request error. ### Parameters | Parameter | Type | Description | Constraints | | :-------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- | | qrcodes | Array of [QRCodesInBulk](schemas-2#QRCodesInBulk) objects | It contains the details of the created QR codes and the error details for those that could not be created. **Since this is a `json` array, the order of the `qrcodes` in the response matches the order of the `qrcodes` in the request.** | | ## Response codes | HTTP status | Description | | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | A 200 response status code implies that at least 1 iDEAL QR transaction was successfully created, so a **Bulk `qrcodes` response** will be returned. This response does not guarantee that all iDEAL QR codes on the request have been created, so you must check the response body to identify the ones that have been created. For those QR codes with a client request error, you can fix the request and create a new bulk request, but as a best practice, **include only the QR codes that failed in the original request** (This is to avoid duplicates). | | 4XX | Client error response. This response is given when the User input was incorrect or something illegal was attempted. **Bulk error response** or **Bulk `qrcodes` response** can be returned with this status code. (e.g. If the `qrcodes` in the request were processed, but unfortunately none of them could be created, and at least one of the errors is due to a client error on the request (example, when the expiry date was incorrect), then the returned response code will be 4xx with a **Bulk `qrcodes` response** body indicating the errors). | | 5XX | Server error response. **Bulk error response** or **Bulk `qrcodes` response** can be returned with this status code. (e.g. If the `qrcodes` in the request were processed, but unfortunately none of them could be created given a server error (example, when a component of the CM.com Online Payments Api is not available to create the QR codes), then the returned response code will be 5xx with a **Bulk `qrcodes` response** body indicating the server errors). |