Checkout Transactions API

B2CB2XB2C CORE COMMERCEB2X CORE COMMERCEBETA

Trigger payments without using the Checkout UI.

The Checkout Transactions API lets you initiate payments managed by Checkout without using the Checkout UI. For example, you can leverage the Checkout Transactions API to process recurring payments for subscription-based orders.

A Transaction represents a request to the Connector to initiate the payment and send payment information for a specific Cart to the payment service provider (PSP) or gift card management system.
The Checkout's payment lifecycle applies also to payments triggered with the Checkout Transactions API.

Use the Checkout Transactions API to trigger only payments managed by Checkout.

Scope

ScopePermission granted
manage_checkout_transactions:{projectKey}Manage Transactions
view_checkout_transactions:{projectKey}View Transactions

Get Transaction

Get Transaction by ID

GET
https://checkout.{region}.commercetools.com/{projectKey}/transactions/{id}
Returns a Transaction with a given id. Specific Error Codes:
OAuth 2.0 Scopes:
view_checkout_transactions:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
id
​
String
​
id of the Transaction.
region
​
String
​
Region in which the Checkout application is hosted.
Response:
200

Transaction

as
application/json
Request Example:cURL
curl --get https://checkout.{region}.commercetools.com/{projectKey}/transactions/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Transactionjson
{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "transaction-key",
  "application": {
    "typeId": "application",
    "id": "a84d4fe7-ae82-4c3f-8c6c-435e54204fdd"
  },
  "cart": {
    "typeId": "cart",
    "id": "a0e60229-441c-44b0-952b-981a67cbd8c4"
  },
  "order": {
    "typeId": "order",
    "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
  },
  "transactionItems": [
    {
      "type": "Recurring",
      "paymentMethod": {
        "typeId": "payment-method",
        "id": "9dee1785-0e29-4d0c-8f2e-3caeb1e77a3b"
      },
      "connectorDeployment": {
        "typeId": "deployment",
        "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
      },
      "payment": {
        "typeId": "payment",
        "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
      }
    }
  ],
  "transactionStatus": {
    "state": "Failed",
    "errors": [
      {
        "code": "PaymentRejected",
        "message": "Payment d1fec278-22c2-4a1d-8190-8f1e8af5ccfb has been rejected."
      }
    ]
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-18T08:15:29.840Z"
}

Get Transaction by Key

GET
https://checkout.{region}.commercetools.com/{projectKey}/transactions/key={key}
Returns a Transaction with a given key. Specific Error Codes:
OAuth 2.0 Scopes:
view_checkout_transactions:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
key
​
String
​
key of the Transaction.
region
​
String
​
Region in which the Checkout application is hosted.
Response:
200

Transaction

as
application/json
Request Example:cURL
curl --get https://checkout.{region}.commercetools.com/{projectKey}/transactions/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Transactionjson
{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "transaction-key",
  "application": {
    "typeId": "application",
    "id": "a84d4fe7-ae82-4c3f-8c6c-435e54204fdd"
  },
  "cart": {
    "typeId": "cart",
    "id": "a0e60229-441c-44b0-952b-981a67cbd8c4"
  },
  "order": {
    "typeId": "order",
    "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
  },
  "transactionItems": [
    {
      "type": "Recurring",
      "paymentMethod": {
        "typeId": "payment-method",
        "id": "9dee1785-0e29-4d0c-8f2e-3caeb1e77a3b"
      },
      "connectorDeployment": {
        "typeId": "deployment",
        "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
      },
      "payment": {
        "typeId": "payment",
        "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
      }
    }
  ],
  "transactionStatus": {
    "state": "Failed",
    "errors": [
      {
        "code": "PaymentRejected",
        "message": "Payment d1fec278-22c2-4a1d-8190-8f1e8af5ccfb has been rejected."
      }
    ]
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-18T08:15:29.840Z"
}

Create Transaction

POST
https://checkout.{region}.commercetools.com/{projectKey}/transactions
Creates a Transaction on Checkout. Requests to the payment Connector time out after 30 seconds.

Specific Error Codes:

OAuth 2.0 Scopes:
manage_checkout_transactions:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
region
​
String
​
Region in which the Checkout application is hosted.
Request Body:TransactionDraftasapplication/json
Response:
201

Transaction

as
application/json
Request Example:cURL
curl https://checkout.{region}.commercetools.com/{projectKey}/transactions -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "transaction-key",
  "application" : {
    "typeId" : "application",
    "id" : "a84d4fe7-ae82-4c3f-8c6c-435e54204fdd"
  },
  "cart" : {
    "typeId" : "cart",
    "id" : "a0e60229-441c-44b0-952b-981a67cbd8c4"
  },
  "transactionItems" : [ {
    "type" : "Recurring",
    "paymentMethod" : {
      "typeId" : "payment-method",
      "id" : "9dee1785-0e29-4d0c-8f2e-3caeb1e77a3b"
    },
    "connectorDeployment" : {
      "typeId" : "deployment",
      "id" : "4c24762b-87df-4bd3-898a-bafed913a9ca"
    }
  } ]
}
DATA
201 Response Example: Transactionjson
{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "transaction-key",
  "application": {
    "typeId": "application",
    "id": "a84d4fe7-ae82-4c3f-8c6c-435e54204fdd"
  },
  "cart": {
    "typeId": "cart",
    "id": "a0e60229-441c-44b0-952b-981a67cbd8c4"
  },
  "order": {
    "typeId": "order",
    "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
  },
  "transactionItems": [
    {
      "type": "Recurring",
      "paymentMethod": {
        "typeId": "payment-method",
        "id": "9dee1785-0e29-4d0c-8f2e-3caeb1e77a3b"
      },
      "connectorDeployment": {
        "typeId": "deployment",
        "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
      },
      "payment": {
        "typeId": "payment",
        "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
      }
    }
  ],
  "transactionStatus": {
    "state": "Failed",
    "errors": [
      {
        "code": "PaymentRejected",
        "message": "Payment d1fec278-22c2-4a1d-8190-8f1e8af5ccfb has been rejected."
      }
    ]
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-18T08:15:29.840Z"
}

Representations

Transaction

Information for the request to the Connector to initiate the payment for a specific Cart.
id​
String​

Unique identifier of the Transaction.

version​
Int​

Current version of the Transaction.

key​
String​

User-defined unique identifier of the Transaction.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
application​
ApplicationReference​
Application for which the payment must be executed.
transactionItems​
Array of TransactionItem​

Transaction Item associated with the Transaction.

MinItems: 1​MaxItems: 1​
cart​
CartReference​
Reference to the Cart for which the payment must be executed.
transactionStatus​
TransactionStatus​

Status of the Transaction.

order​
OrderReference​
Reference to the Order created from the Cart when the Transaction is completed.
createdAt​
DateTime​

Date and time (UTC) the Transaction was initially created.

lastModifiedAt​
DateTime​

Date and time (UTC) the Transaction was last updated.

TransactionDraft

key​
String​

User-defined unique identifier of the Transaction.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
application​
ApplicationResourceIdentifier​
Application for which the payment is executed.
transactionItems​
Array of TransactionItemDraft​

Transaction Item associated with the Transaction.

MinItems: 1​MaxItems: 1​
cart​
CartResourceIdentifier​
Cart for which the payment must be executed.

TransactionItem

Payment information related to the Transaction. If type is not present, this is a TransactionItemPaymentIntegration. Each supported payment flow has its own corresponding Transaction Item type, like TransactionItemRecurring.
type​
String​
Type of the Transaction Item, matching the type of the TransactionItemDraft it was created from. Not present for Transaction Items created without an explicit type.
amount​
Amount​

Money value of the Transaction Item.

payment​
PaymentReference​
Reference to the Payment associated with the Transaction Item.

TransactionItemPaymentIntegration

A Transaction Item processed through a Payment Integration. This is the default Transaction Item type used when type is not present.
type​
String​

Not present for TransactionItemPaymentIntegration.

amount​
Amount​

Money value of the Transaction Item.

payment​
PaymentReference​
Reference to the Payment associated with the Transaction Item.
paymentIntegration​
PaymentIntegrationReference​
Reference to the Payment Integration used to execute the payment.

TransactionItemRecurring BETA

A Transaction Item processing a recurring payment for a PaymentMethod.
type​
String​
"Recurring"
Type of the Transaction Item, matching the type of the TransactionItemDraft it was created from. Not present for Transaction Items created without an explicit type.
amount​
Amount​

Money value of the Transaction Item.

payment​
PaymentReference​
Reference to the Payment associated with the Transaction Item.
paymentMethod​
PaymentMethodReference​
Reference to the PaymentMethod charged for the Transaction Item.
connectorDeployment​
ConnectorDeploymentReference​

Reference to the connector deployment used to execute the payment.

TransactionItemDraft

Base type for creating a Transaction Item. If type is omitted, a TransactionItemPaymentIntegrationDraft is created to process the payment through a Payment Integration. Each supported payment flow has its own corresponding Transaction Item Draft type, like TransactionItemRecurringDraft.
type​
String​

Type of the Transaction Item to create.

amount​
Amount​
Money value of the Transaction Item. If not present, the Connector resolves the amount from the Cart.

TransactionItemPaymentIntegrationDraft

Creates a Transaction Item that is processed through a Payment Integration. This is the default Transaction Item type used when type is omitted.
type​
String​

Must not be set for TransactionItemPaymentIntegrationDraft.

amount​
Amount​
Money value of the Transaction Item. If not present, the Connector resolves the amount from the Cart.
paymentIntegration​
PaymentIntegrationResourceIdentifier​
Resource Identifier of the Payment Integration to use to execute the payment.

TransactionItemRecurringDraft BETA

Creates a Transaction Item to process a recurring payment for a PaymentMethod using a specific connector deployment. The Cart referenced by the Transaction must have the same customerId as the referenced PaymentMethod.
type​
String​
"Recurring"

Type of the Transaction Item to create.

amount​
Amount​
Money value of the Transaction Item. If not present, the Connector resolves the amount from the Cart.
paymentMethod​
PaymentMethodReference​
Reference to the PaymentMethod to charge. The PaymentMethod must belong to the same customer as the Cart referenced by the Transaction.
connectorDeployment​
ConnectorDeploymentReference​

Reference to the connector deployment to use to execute the payment.

TransactionStatus

The state of the Transaction and the related errors in case of a failed Transaction.
state​
TransactionState​

State of the Transaction.

errors​
Array of TransactionError​
Errors returned if the Transaction is in the Failed state.

TransactionState

The state of the Transaction.
Initial
The Transaction has started. The Connector is requesting the PSP or gift card management system to execute the payment for the Cart.
Pending

The Transaction is in progress. The PSP or gift card management system is processing the payment.

Completed
The Transaction completed successfully. The PSP or gift card management system processed the payment and Checkout created an Order from the Cart.
Failed

The Transaction failed.

TransactionError

A single error on the Transaction. Multiple errors may be included in the Transaction Status.
code​
String​

Error identifier.

message​
String​

Plain text description of the cause of the error.