Documentation
BETA

Checkout Payment Intents API

Capture, refund, and cancel an authorized Payment.

After a Payment has been authorized and Checkout has created an Order, you might need to perform actions on the Payment during its lifecycle. The Checkout Payment Intents API lets you send requests to capture, refund, or cancel an authorized Payment.
Following your request via the Checkout Payment Intents API, Checkout will request the payment service provider (PSP) to perform the related financial process.

Use the Payment Intents API only for payments created by Checkout.

Scope

ScopePermission granted
manage_checkout_payment_intents:{projectKey}Send capture, refund, or cancel requests to the payment service provider (PSP) and update the Payment by calling the payment Connector.

Representations

PaymentIntentAction

Depending on the action specified, Checkout requests the payment service provider (PSP) to capture, refund, or cancel the authorization for the given Payment.

action​
PaymentIntentOperation​

Action to execute for the given Payment.

amount​
Amount​

Amount to be captured or refunded.

PaymentIntentOperation

The possible values for a Payment Intent Action.

capturePayment

Captures the given Payment amount.

refundPayment

Refunds the given Payment amount.

cancelPayment

Cancels an authorized Payment.

Manage Payment by ID

POST
https://checkout.{region}.commercetools.com/{projectKey}/payment-intents/{paymentId}

Specific Error Codes:

OAuth 2.0 Scopes:
manage_checkout_payment_intents:{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.

paymentId
​
String
​

id of the Payment.

Request Body:
application/json
actions​
Array of PaymentIntentAction​

Action to execute for the given Payment.

MinItems: 1​MaxItems: 1​
Response:
200

any

asapplication/json
Request Example:cURL
curl https://checkout.{region}.commercetools.com/{projectKey}/payment-intents/{paymentId} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "actions" : [ {
    "action" : "capturePayment",
    "amount" : {
      "centAmount" : 10000,
      "currencyCode" : "EUR"
    }
  } ]
}
DATA
200 Response Example: anyjson
{}

Manage Payment Intents actions

Capture Payment

Requests to capture the given amount from the customer. Checkout will request the PSP to proceed with the financial process to capture the amount.

action​
String​
"capturePayment"
amount​
Amount​

Amount to be captured. It must be less than or equal to the authorized amount.

Example: json
{
  "action": "capturePayment",
  "amount": {
    "centAmount": 10000,
    "currencyCode": "EUR"
  }
}

Refund Payment

Requests to refund the given amount to the customer. Checkout will request the PSP to proceed with the financial process to refund the amount.

action​
String​
"refundPayment"
amount​
Amount​

Amount to be refunded. It must be less than or equal to the captured amount.

Example: json
{
  "action": "refundPayment",
  "amount": {
    "centAmount": 10000,
    "currencyCode": "EUR"
  }
}

Cancel Payment

Requests to cancel the authorization for a Payment. Checkout will cancel the Payment and will request the PSP to proceed with the financial process to cancel the authorization.

You cannot request to cancel the authorization for a Payment that has already been captured.

action​
String​
"cancelPayment"
Example: json
{
  "action": "cancelPayment"
}