Checkout Payments API

Capture, refund, and cancel an authorized Payment.

After a Payment has been authorized and commercetools 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

Scope	Permission 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

PaymentAction

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

`action` PaymentOperation	Action to execute for the given Payment.
`amount` 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}

Specific Error Codes:

MultipleActionsNotAllowed
RequiredField
ResourceNotFound

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

Refund Payment

Cancel Payment

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"
}

Errors

500 Internal Server Error -GeneralError

400 Bad Request -MultipleActionsNotAllowed -RequiredField

404 Not Found -ResourceNotFound

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."`