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": [
    {
      "paymentIntegration": {
        "typeId": "payment-integration",
        "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
      },
      "amount": {
        "centAmount": 1000,
        "currencyCode": "EUR"
      },
      "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": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

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": [
    {
      "paymentIntegration": {
        "typeId": "payment-integration",
        "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
      },
      "amount": {
        "centAmount": 1000,
        "currencyCode": "EUR"
      },
      "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": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Create Transaction

POST
https://checkout.{region}.commercetools.com/{projectKey}/transactions

Creates a Transaction on Checkout. 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" : [ {
    "paymentIntegration" : {
      "typeId" : "payment-integration",
      "id" : "4c24762b-87df-4bd3-898a-bafed913a9ca"
    },
    "amount" : {
      "centAmount" : 1000,
      "currencyCode" : "EUR"
    }
  } ]
}
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": [
    {
      "paymentIntegration": {
        "typeId": "payment-integration",
        "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
      },
      "amount": {
        "centAmount": 1000,
        "currencyCode": "EUR"
      },
      "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": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

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.
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 to use to execute the payment.

TransactionItemDraft

paymentIntegration​
PaymentIntegrationResourceIdentifier​
Resource Identifier of the Payment Integration to use to execute the payment.
amount​
Amount​

Money value of the Transaction Item.

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.