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.

Request

POST https://api.pay.cm.com/api/v1/paymentmethods/idealqr/v1/bulk

{
  "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": [
    {},
    {},
    {}
  ]
}

{
  "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"
      }
    }
  ]
}

{
  "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 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 Object	The default values that will be used for the creation of the QR codes specified in `qrcodes`.

Response

{
  "error": {
    "id": "709d2be7-62e1-4cd6-a0f0-80b19209acaf",
    "message": "Invalid request message"
  }
}

{
  "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"
      }
    }
  ]
}

{
  "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 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 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).

Prerequisite

Request

Parameters

Optional parameters

Response

Bulk error response

Parameters

Bulk qrcodes response

Parameters

Response codes

Bulk `qrcodes` response