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.

Request

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:

{
  "reference": "20210623130413",
  "amount": 1200,
  "currency": "EUR",
  "consumer": {
    "givenName": "John",
    "middleName": "",
    "familyName": "Doe",
    "email": "[email protected]",
    "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"
  }
}
{
  "reference": "20210623130413",
  "amount": 1200,
  "currency": "EUR",
  "consumer": {
    "givenName": "John",
    "middleName": "",
    "familyName": "Doe",
    "email": "[email protected]",
    "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"
}
{
  "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

ParameterTypeDescriptionConstraints
referenceString(1...255)An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload.
amountInt(1...99999999)Integer representing the amount of the checkout. Denomination in the smallest currency subunit (e.g. eurocents).
merchantOrderReferenceString(1...35)Identification of the order within your system. Ultimately appears on the payment confirmation (statement and confirmation screen).
descriptionString(1...255)Description of the transaction.
expiresAtString(RFC3339)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.ISO 8601 date and time.
languageString(ISO 639-1)Preferred language of the user interface.The available languages are: [ cs, da, de, en, es, fi, fr, hu, it, nl, no, pl, pt, sv, tr ].
returnUrlString(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.
returnUrlsreturnUrls ObjectSpecifies 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

ParameterTypeDescriptionConstraints
currencyString (ISO 4217)Currency code.ISO 4217 currency code.
consumerconsumerInRequest ObjectCustomer details.If consumer is provided then the following fields are mandatory: givenName, familyName, email, phone.

If consumer.address is provided then the following fields are mandatory: street, houseNumber, postalCode, city, countryCode.
paymentMethodsArray of stringsWith this field you can optionally select a subset of payment methods to be shown to your customer.The available payment methods are: [ bancontact, creditcard, ideal, maestro, belfius, giropay, klarna, blik, przelewy24, elv, google_pay, apple_pay, in3 ]. The selected payment methods must be enabled for your account.
webhooksArray of objectsWebhooks enable receiving a web request once a given event occurs.Find more details here.
maxRetriesInt(0...255)Maximum number of retries allowed to pay the checkout.
orderItemsArray of orderItem objectsRequired only for the some payment methods (e.g. Klarna).If orderItems is provided then the following fields are mandatory: code, unitPrice, quantity, vatAmount ,vatRate .

Response

{
  "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  "reference": "20210623130413",
  "amount": 1200,
  "currency": "EUR",
  "consumer": {
    "givenName": "John",
    "middleName": "",
    "familyName": "Doe",
    "email": "[email protected]",
    "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

ParameterTypeDescriptionConstraints
idString(36)Transaction unique identifier.
referenceString(1...255)An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload.Specified in the request.
amountInt(1...99999999)Integer representing the amount of the checkout. Denomination in the smallest currency subunit (e.g. eurocents).Specified in the request.
currencyString (ISO 4217)Currency code.Specified in the request.
merchantOrderReferenceString(1...35)Identification of the order within your system. Ultimately appears on the payment confirmation (statement and confirmation screen).Specified in the request.
descriptionString(1...255)Description of the transaction.Specified in the request.
expiresAtString(RFC3339)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.Specified in the request.
statusStringOPEN - Checkout has been created. This is the initial status.
SUCCESS - Checkout successfully paid.
CANCELLED - Checkout has been cancelled by your customers.
EXPIRED - Checkout has not succeeded; expired.
FAILURE - Checkout has not succeeded; unknown reason.
AUTHORIZED - Checkout payment is authorized.
PENDING - Checkout payment could not be completed yet; waiting for something.
actionaction ObjectThe next action to be performed by you for this transaction. This includes a URL where you should redirect your customer to perform the payment.This parameter is nullable, and it is only available while the transaction is OPEN.
createdAtString(RFC3339)Creation time.ISO 8601 date and time.
returnUrlString(2000)Specifies the URL where your customers will be redirected to when the payment process is completed.Specified in the request.
returnUrlsObjectSpecifies 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.Specified in the request.

Optional parameters

ParameterTypeDescriptionConstraints
consumerObjectCustomer details.Specified in the request or by the configuration of your account.
paymentMethodsArray of stringsSelected payment methods to be shown to your customer.Specified in the request or by the configuration of your account.
orderItemsArray of objectsRequired only for the some payment methods (e.g. Klarna).Specified in the request.
languageString(ISO 639-1)Preferred language of the user interface.Specified in the request.
webhooksArray of objectsWebhooks enable receiving a web request once a given event occurs.Specified in the request.
maxRetriesInt(0...255)Maximum number of retries allowed to pay the checkout.Specified in the request.
refundsrefund ObjectIndicates refundedAmount and refundedPendingAmount.

Response codes

HTTP statusDescription
201Successful transaction.
4XXClient 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).
5XXServer error response (See message for details).