Checkout Transactions API

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 payment Connector to initiate the payment and send payment information for a specific Cart to the payment service provider (PSP).

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

Scope	Permission granted
`manage_checkout_transactions:{projectKey}`	Manage Transactions
`view_checkout_transactions:{projectKey}`	View Transactions

Representations

Transaction

Information for the request to the payment 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` ApplicationResourceIdentifier	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.

`paymentIntegration` PaymentIntegrationReference	Reference to the Payment Integration to use to execute the payment.
`amount` Amount	Money value of the Transaction Item.
`payment` PaymentReference	Reference to the Payment associated with the Transaction Item.

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 payment Connector is requesting the PSP to execute the payment for the Cart.
Pending: The Transaction is in progress. The PSP is processing the payment.
Completed: The Transaction completed successfully. The PSP 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.

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:

`region` String	Region in which the Checkout application is hosted.
`projectKey` String	Identifier of your Checkout entity and `key` of your Project.
`id` String	`id` of the Transaction.

Response:

200Transactionasapplication/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:

`region` String	Region in which the Checkout application is hosted.
`projectKey` String	Identifier of your Checkout entity and `key` of your Project.
`key` String	`key` of the Transaction.

Response:

200Transactionasapplication/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:

`region` String	Region in which the Checkout application is hosted.
`projectKey` String	Identifier of your Checkout entity and `key` of your Project.

Request Body:TransactionDraftasapplication/json

Response:

201Transactionasapplication/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"
}