Checkout Payment Intents API

B2CB2X

Capture, refund, reverse, 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, reverse, or cancel an authorized Payment.
Following your request via the Checkout Payment Intents API, Checkout will request the payment service provider (PSP) or gift card management system 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, reverse, or cancel requests to the payment service provider (PSP) or gift card management system and update the Payment by calling the payment Connector.

Representations

PaymentIntentAction

Depending on the action specified, Checkout requests the payment service provider (PSP) or gift card management system to capture, refund, or cancel the authorization for the given Payment.
action​
PaymentIntentOperation​
Action to execute for the given Payment.

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.
reversePayment
Reverses a Payment.

PaymentIntentResponse

Returned by Checkout after forwarding a Payment Intent request to the payment Connector. If the Connector response does not contain a valid outcome value, Checkout returns a 500 Internal Server Error.
outcome​
PaymentIntentOutcome​
The outcome of the Payment Intent as reported by the payment Connector.
Example: json
{
  "outcome": "approved"
}

PaymentIntentOutcome

The outcome returned by the payment Connector after processing a Payment Intent.

approved

The Payment Intent was processed and approved by the payment service provider (PSP).

rejected

The Payment Intent was rejected by the payment service provider (PSP).

received

The Payment Intent was received and is being processed asynchronously by the payment service provider (PSP).

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:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
paymentId
​
String
​
id of the Payment.
region
​
String
​
Region in which the Checkout application is hosted.
Request Body:
application/json
actions​
Array of PaymentIntentAction​

Action to execute for the given Payment.

MinItems: 1​MaxItems: 1​
Response:
200

PaymentIntentResponse

as
application/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"
    },
    "merchantReference" : "example-reference"
  } ]
}
DATA
200 Response Example: PaymentIntentResponsejson
{
  "outcome": "approved"
}

Manage Payment Intents actions

Capture Payment

Requests to capture the given amount from the customer. Checkout will request the PSP or gift card management system to proceed with the financial process to capture the amount.
action​
PaymentIntentOperation​
capturePayment
Action to execute for the given Payment.
amount​
Amount​
Amount to be captured. It must be less than or equal to the authorized amount.
merchantReference​
String​
A merchant-defined identifier associated with the Payment to track and reconcile the Payment Intent Action on the merchant's side. For example, an invoice number.
Example: json
{
  "action": "capturePayment",
  "amount": {
    "centAmount": 10000,
    "currencyCode": "EUR"
  },
  "merchantReference": "example-reference"
}

Refund Payment

Requests to refund the given amount to the customer. Checkout will request the PSP or gift card management system to proceed with the financial process to refund the amount.
action​
PaymentIntentOperation​
refundPayment
Action to execute for the given Payment.
amount​
Amount​
Amount to be refunded. It must be less than or equal to the captured amount.
transactionId​
String​

The identifier of the capture transaction that is associated with the refund action.

merchantReference​
String​
A merchant-defined identifier associated with the Payment to track and reconcile the Payment Intent Action on the merchant's side. For example, an invoice number.
Example: json
{
  "action": "refundPayment",
  "amount": {
    "centAmount": 10000,
    "currencyCode": "EUR"
  },
  "transactionId": "example-transactionId",
  "merchantReference": "example-reference"
}

Cancel Payment

Requests to cancel the authorization for a Payment. Checkout will cancel the Payment and will request the PSP or gift card management system 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​
PaymentIntentOperation​
cancelPayment
Action to execute for the given Payment.
merchantReference​
String​
A merchant-defined identifier associated with the Payment to track and reconcile the Payment Intent Action on the merchant's side. For example, an invoice number.
Example: json
{
  "action": "cancelPayment",
  "merchantReference": "example-reference"
}

Reverse Payment

To use Automated Reversals, the Connectors in your Project must support the reversePayment action.
Requests to reverse a Payment. Checkout reverses the Payment, and then requests the PSP or gift card management system to proceed with the relevant process to reverse the Payment.
action​
PaymentIntentOperation​
reversePayment
Action to execute for the given Payment.
merchantReference​
String​
A merchant-defined identifier associated with the Payment to track and reconcile the Payment Intent Action on the merchant's side. For example, an invoice number.
Example: json
{
  "action": "reversePayment",
  "merchantReference": "example-reference"
}