Checkout Payments 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 Payments API lets you send requests to capture, refund, or cancel an authorized Payment.
Following your request via the Checkout Payments API, Checkout will request the Payment Service Provider (PSP) to perform the related financial process.

Scope

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

Representations

PaymentAction

Depending on the action specified, Checkout requests the Payment Service Provider to capture, refund, or cancel the authorization for the given Payment.

action

Action to execute for the given Payment.

amount

Amount to be captured or refunded.

Amount

The amount related to a payment action.

centAmount
Int

Amount in the smallest indivisible unit of a currency, such as:

  • Cents for EUR and USD, pence for GBP, or centime for CHF (5 CHF is specified as 500).
  • The value in the major unit for currencies without minor units, like JPY (5 JPY is specified as 5).
currencyCode
String

Currency code compliant to ISO 4217.

Pattern: ^[A-Z]{3}$

PaymentOperation

The possible values for a payment action.

capturePayment

Captures the given Payment amount.

refundPayment

Refunds the given Payment amount.

cancelPayment

Cancels an authorized Payment.

Region

The Region in which the Checkout application is hosted.

europe-west1.gcp

for Europe (Google Cloud, Belgium)

us-central1.gcp

for North America (Google Cloud, Iowa)

australia-southeast1.gcp

for Australia (Google Cloud, Sydney)

Manage Payment by ID

POST
https://checkout.{region}.commercetools.com/{projectKey}/payment-intents/{paymentId}
OAuth 2.0 Scopes:
manage_checkout_payment_intents:{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 PaymentAction

Action to execute for the given Payment.

MinItems: 1MaxItems: 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 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 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 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"
}

Errors

500 Internal Server Error

The following general error code can appear in responses with the HTTP status code 500:

GeneralError

Returned when a server-side problem occurs. In some cases, the requested action may successfully complete after the error is returned. Therefore, it is recommended to verify the status of the requested resource after receiving a 500 error.

If you encounter this error, report it using the Support Portal.

code
String
"General"
message
String

Description about any known details of the problem, for example, "Write operations are temporarily unavailable".

400 Bad Request

The following error codes can appear in responses with the HTTP status code 400:

MultipleActionsNotAllowed

Returned when actions in the request body contains more than one object.

code
String
"MultipleActionsNotAllowed"
message
String

"Actions accepts only one action at time. Array size must be 1."

RequiredField

Returned when a value is not defined for a required field.

code
String
"RequiredField"
message
String

"A value is required for field $field."

field
String

Name of the field missing the value.

404 Not Found

The following error code can appear in responses with the HTTP status code 404:

ResourceNotFound

Returned when the resource addressed by the request URL does not exist.

code
String
"ResourceNotFound"
message
String

"The Resource with ID $resourceId was not found."