# Create Transaction You can use this call to create a new Checkout 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/checkout/v1/transactions ``` ### Request body examples These are only some examples of the request body to create a transaction: ```json Full Request with ReturnURLs { "reference": "20210623130413", "amount": 1200, "currency": "EUR", "consumer": { "givenName": "John", "middleName": "", "familyName": "Doe", "email": "john.doe@email.tld", "gender": null, "address": { "street": "Rustenburgerlaan", "houseNumber": "25", "postalCode": "2012AL", "city": "Haarlem", "countryCode": "NL", "state": "Noord-Holland", "additionalData": "Right-hand portal" }, "phone": "06-95613259", "dateOfBirth": "1996-12-01" }, "merchantOrderReference": "order123", "description": "Order at yourdomain.tld", "paymentMethods": [ "ideal", "bancontact", "klarna" ], "orderItems": [ { "code": "SDC4/32GB-2ADP", "name": "Kingston microSD 32GB", "description": "Best seller SD card", "unitPrice": 600, "quantity": 2, "vatAmount": 100, "vatRate": 20 } ], "expiresAt": "2006-01-02T15:04:05Z", "language": "nl", "webhooks": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "REFUND_STATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "STATUS_CHANGE" ] } ], "maxRetries": 10, "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 { "reference": "20210623130413", "amount": 1200, "currency": "EUR", "consumer": { "givenName": "John", "middleName": "", "familyName": "Doe", "email": "john.doe@email.tld", "gender": null, "address": { "street": "Rustenburgerlaan", "houseNumber": "25", "postalCode": "2012AL", "city": "Haarlem", "countryCode": "NL", "state": "Noord-Holland", "additionalData": "Right-hand portal" }, "phone": "06-95613259", "dateOfBirth": "1996-12-01" }, "merchantOrderReference": "order123", "description": "Order at yourdomain.tld", "paymentMethods": [ "ideal", "bancontact", "klarna" ], "orderItems": [ { "code": "SDC4/32GB-2ADP", "name": "Kingston microSD 32GB", "description": "Best seller SD card", "unitPrice": 600, "quantity": 2, "vatAmount": 100, "vatRate": 20 } ], "expiresAt": "2006-01-02T15:04:05Z", "language": "nl", "webhooks": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "REFUND_STATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "STATUS_CHANGE" ] } ], "maxRetries": 10, "returnUrl": "https://yourdomain.tld/order/payment-completed.html" } ``` ```json Minimal Request with ReturnURLs { "reference": "20210623130413", "amount": 1200, "merchantOrderReference": "order123", "description": "Order at yourdomain.tld", "expiresAt": "2006-01-02T15:04:05Z", "language": "nl", "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" } } ``` "**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 [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "h-3": "Constraints", "0-0": "reference", "0-1": "String(1...255)", "0-2": "An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload.", "0-3": "", "1-0": "amount", "1-1": "Int(1...99999999)", "1-2": "Integer representing the amount of the checkout. Denomination in the smallest currency subunit (e.g. eurocents). **If `orderItems` is provided, then a calculated amount, based on the sum of the product of item.UnitPrice and item.Quantity for all the items, will be used as checkout amount instead of the value provided in this field.**", "1-3": "For payment methods like in3, this value should be `>= 5000 cents`. **If in3 is enabled on your configuration, the amount (or calculated amount based on the orderItems) is `<5000 cents`, and you did not specify in3 in the `paymentMethods` request parameter, then you will NOT see in3 in the `paymentMethods` response parameter (so it will not be included in the checkout payment method selection page). If in3 is enabled on your configuration, the amount (or calculated amount based on the orderItems) is `<5000 cents`, but if you specify in3 in the `paymentMethods` request parameter, then you will get a validation error while creating the checkout transaction.** \n \nCertain payment methods require a minimum amount of 2 cents because of legacy. These include [creditcard, ideal*, bancontact, apple-pay, google-pay, paypal, klarna].\\*ideal -> depending our the configuration of your account 1 cent transactions are possible.", "2-0": "merchantOrderReference", "2-1": "String(1...35)", "2-2": "Identification of the order within your system. Ultimately appears on the payment confirmation (statement and confirmation screen).", "2-3": "Must be an alphanumeric value", "3-0": "description", "3-1": "String(1...35)", "3-2": "Description of the transaction.", "3-3": "", "4-0": "language", "4-1": "String(ISO 639-1)", "4-2": "Preferred language of the user interface.", "4-3": "The available languages are: `[ cs, da, de, en, es, fi, fr, hu, it, nl, no, pl, pt, sv, tr ]`.", "5-0": "returnUrl", "5-1": "String(2000)", "5-2": "Specifies the URL where your customers will be redirected to when the payment process is completed.", "5-3": "Either `returnUrl` or `returnUrls` must be specified, but not both.", "6-0": "returnUrls", "6-1": "[returnUrls](schemas#returnurls) Object", "6-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`.", "6-3": "Either `returnUrl` or `returnUrls` must be specified, but not both." }, "cols": 4, "rows": 7, "align": [ "left", "left", "left", "left" ] } [/block] ## Optional parameters [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "h-3": "Constraints", "0-0": "expiresAt", "0-1": "String(RFC3339)", "0-2": "Specifies the time at which new payments cannot be started in the Checkout. At the time of expiration the Checkout status will transition to `PENDING` if there are still `OPEN` or `PENDING` payments. Once the payments are no longer `OPEN` or `PENDING` the status of the checkout will transaction to `EXPIRED` or in the case of a successful payment to `SUCCESS`.", "0-3": "ISO 8601 date and time. If left empty, a default value will be set. Find more details [here](expiration) .", "1-0": "currency", "1-1": "String (ISO 4217)", "1-2": "Currency code.", "1-3": "ISO 4217 currency code.", "2-0": "consumer", "2-1": "[consumerInRequest](schemas#consumerInRequest) Object", "2-2": "Customer details.", "2-3": "If `consumer` is provided then the following fields are mandatory: `givenName`, `familyName`, `email`, `phone`. \n \nIf `consumer.address` is provided then the following fields are mandatory: `street`, `houseNumber`, `postalCode`, `city`, `countryCode`. \n \nFor in3, the following consumer details are required: `familyName`, `phone`, `email`, `dateOfBirth`, `address.street`, `address.houseNumber`, `address.postalCode`, `address.city`, and `address.countryCode`. If any required information is missing in the request, then the consumer form will be displayed in the checkout to collect the missing details.", "3-0": "paymentMethods", "3-1": "Array of strings", "3-2": "This parameter indicates which payment methods you want the checkout to make available for your customers on the checkout payment methods selection page. **Note: some payment methods like Klarna or in3 require stricter validation to be enabled. If you specify `klarna` or `in3` in this parameter, then the validation will be done while creating the transaction. If you do not specify them in this parameter, then given your configuration and the other values you provided in your request, it might cause these payment methods not to be included in the `paymentMethods` response parameter (so they will NOT be included on the checkout payment methods selection page).**", "3-3": "The available payment methods are: `[ bancontact, creditcard, ideal, maestro, belfius, klarna, google_pay, apple_pay, in3 ]`. The selected payment methods _must_ be enabled in your configuration.", "4-0": "webhooks", "4-1": "Array of objects", "4-2": "Webhooks enable receiving a web request once a given event occurs.", "4-3": "Find more details [here](webhooks-1).", "5-0": "maxRetries", "5-1": "Int(0...255)", "5-2": "Maximum number of retries allowed to pay the checkout.", "5-3": "", "6-0": "orderItems", "6-1": "Array of [orderItem](schemas#orderitem) objects", "6-2": "Required only for some payment methods (e.g. Klarna or in3). **If (Klarna or in3) is enabled in your configuration, but you did not specify neither `orderItems` on your request nor (Klarna or in3) on the `paymentMethods` request parameter, then you will NOT see (Klarna or in3) on the `paymentMethods` response parameter (so they will not be included in the checkout payment method selection page). If (Klarna or in3) is enabled in your configuration, and you do not specify `orderItems` in your request, but you specify (Klarna or in3) in the `paymentMethods` request parameter, then you will get a validation error while creating the checkout transaction. Apart from that, if `orderItems` is provided, then a calculated amount, based on the sum of the product of item.UnitPrice and item.Quantity for all the items, will be used as checkout amount instead of the value provided as `amount` on the request.** ", "6-3": "" }, "cols": 4, "rows": 7, "align": [ "left", "left", "left", "left" ] } [/block] ## Response ```json { "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d", "reference": "20210623130413", "amount": 1200, "currency": "EUR", "consumer": { "givenName": "John", "middleName": "", "familyName": "Doe", "email": "john.doe@email.tld", "gender": null, "address": { "street": "Rustenburgerlaan", "houseNumber": "25", "postalCode": "2012AL", "city": "Haarlem", "countryCode": "NL", "state": "Noord-Holland", "additionalData": "Right-hand portal" }, "phone": "06-95613259", "dateOfBirth": "1996-12-01" }, "merchantOrderReference": "order123", "description": "Order at yourdomain.tld", "paymentMethods": [ "ideal", "bancontact", "klarna" ], "orderItems": [ { "code": "SDC4/32GB-2ADP", "name": "Kingston microSD 32GB", "description": "Best seller SD card", "unitPrice": 600, "quantity": 2, "vatAmount": 100, "vatRate": 20 } ], "expiresAt": "2006-01-02T15:04:05Z", "language": "nl", "webhooks": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "REFUND_STATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "STATUS_CHANGE" ] } ], "maxRetries": 10, "status": "OPEN", "action": { "redirect": { "url": "https://checkout.cmpayments.com/?hostedCheckoutId=0863a7aadb99bf1c6ae770936db45eb33e61c917" } }, "createdAt": "2006-01-02T15:04:05Z", "refunds": { "refundedAmount": 300, "refundedPendingAmount": 100 }, "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": "merchantOrderReference", "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": "expiresAt", "6-1": "String(RFC3339)", "6-2": "Specifies the time at which new payments cannot be started in the Checkout. At the time of expiration the Checkout status will transition to `PENDING` if there are still `OPEN` or `PENDING` payments. Once the payments are no longer `OPEN` or `PENDING` the status of the checkout will transaction to `EXPIRED` or in the case of a successful payment to `SUCCESS`.", "6-3": "Specified in the request.", "7-0": "status", "7-1": "String", "7-2": "`OPEN` - Checkout has been created. This is the initial status. \n`SUCCESS` - Checkout successfully paid. \n`CANCELLED` - Checkout has been cancelled by your customers. \n`EXPIRED` - Checkout has not succeeded; expired. \n`FAILURE` - Checkout has not succeeded; unknown reason. \n`AUTHORIZED` - Checkout payment is authorized. \n`PENDING` - Checkout payment could not be completed yet; waiting for something.", "7-3": "", "8-0": "action", "8-1": "[action](schemas#action) Object", "8-2": "The next action to be performed by you for this transaction. This includes a URL where you should `redirect` your customer to perform the payment.", "8-3": "This parameter is nullable, and it is only available while the transaction is `OPEN`.", "9-0": "createdAt", "9-1": "String(RFC3339)", "9-2": "Creation time.", "9-3": "ISO 8601 date and time.", "10-0": "returnUrl", "10-1": "String(2000)", "10-2": "Specifies the URL where your customers will be redirected to when the payment process is completed.", "10-3": "Specified in the request.", "11-0": "returnUrls", "11-1": "Object", "11-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`.", "11-3": "Specified in the request." }, "cols": 4, "rows": 12, "align": [ "left", "left", "left", "left" ] } [/block] ## Optional parameters | Parameter | Type | Description | Constraints | | :------------- | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | consumer | Object | Customer details. | Specified in the request or by the configuration of your account. | | paymentMethods | Array of strings | This is an important field because here **you can validate which payment methods will be available for your customers on the checkout payment method selection page**. | **Even if you provided specific values as `paymentMethods` in your request, the value in the response might not be the same, given that it also depends on your configuration and on other values you provided in your request. For this reason, it is recommended that you always check this value in the response.** | | orderItems | Array of objects | Required only for some payment methods (e.g. Klarna or in3). | 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. | | maxRetries | Int(0...255) | Maximum number of retries allowed to pay the checkout. | Specified in the request. | | refunds | [refund](schemas#refund) Object | Indicates refundedAmount and refundedPendingAmount. | | ## 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). |