Documentation

Payments

A Payment represents a series of logically connected financial transactions like reserving, charging, or refunding money.

A Payment holds information about the payment service provider (PSP), the payment method used, any related transactions, and the current state of the Payment. An Order or a Cart can reference a set of Payments using the PaymentInfo object. A Payment can also reference a Customer, or an anonymous session.

The actual financial process is carried out by an external PSP, which is connected to Composable Commerce by PSP-specific integrations.

If you are using Checkout for your checkout solution, the Checkout Payments API lets you request the PSP to perform actions throughout the financial process, such as payment capture, refund, and authorization cancellation.

Representations

Payment

id​
String​

Unique identifier of the Payment.

version​
Int​

Current version of the Payment.

key​
String​

User-defined unique identifier of the Payment.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
customer​
CustomerReference​

Reference to a Customer associated with the Payment.

anonymousId​
String​

Anonymous session associated with the Payment.

interfaceId​
String​

Identifier used by the payment service that processes the Payment (for example, a PSP). The combination of interfaceId and the paymentInterface field on PaymentMethodInfo must be unique.

amountPlanned​
CentPrecisionMoney​

Money value the Payment intends to receive from the customer. The value typically matches the Cart or Order gross total.

paymentMethodInfo​
PaymentMethodInfo​

Information regarding the payment interface (for example, a PSP), and the specific payment method used.

paymentStatus​
PaymentStatus​

Current status of the Payment.

transactions​
Array of Transaction​

Financial transactions of the Payment. Each Transaction has a TransactionType and a TransactionState.

interfaceInteractions​
Array of CustomFields​

Represents information exchange with the payment service, for example, a PSP. An interaction may be a request sent, or a response or notification received from the payment service.

custom​
CustomFields​

Custom Fields for the Payment.

createdAt​
DateTime​

Date and time (UTC) the Payment was initially created.

createdBy​BETA
CreatedBy​

IDs and references that created the Payment.

lastModifiedAt​
DateTime​

Date and time (UTC) the Payment was last updated.

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the Payment.

PaymentDraft

key​
String​

User-defined unique identifier for the Payment.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
customer​
CustomerResourceIdentifier​

Reference to a Customer associated with the Payment.

anonymousId​
String​

Anonymous session associated with the Payment.

interfaceId​
String​

Identifier used by the payment service that processes the Payment (for example, a PSP). The combination of interfaceId and the paymentInterface field on PaymentMethodInfo must be unique. Once set, it cannot be changed.

amountPlanned​
Money​

Money value the Payment intends to receive from the customer. The value typically matches the Cart or Order gross total.

paymentMethodInfo​
PaymentMethodInfo​

Information regarding the payment interface (for example, a PSP), and the specific payment method used.

paymentStatus​
PaymentStatusDraft​

Current status of the Payment.

transactions​
Array of TransactionDraft​

Financial transactions of the Payment. Each Transaction has a TransactionType and a TransactionState.

interfaceInteractions​
Array of CustomFieldsDraft​

Represents information exchange with the payment service, for example, a PSP. An interaction may be a request sent, or a response or notification received from the payment service.

custom​
CustomFieldsDraft​

Custom Fields for the Payment.

PaymentPagedQueryResponse

PagedQueryResult with results containing an array of Payment.

limit​
Int​

Number of results requested.

count​
Int​

Actual number of results returned.

total​
Int​

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

offset​
Int​

Number of elements skipped.

results​
Array of Payment​

Payments matching the query.

PaymentReference

Reference to a Payment.

id​
String​

Unique identifier of the referenced Payment.

typeId​
ReferenceTypeId​
"payment"

References a Payment.

obj​
Payment​

Contains the representation of the expanded Payment. Only present in responses to requests with Reference Expansion for Payments.

PaymentResourceIdentifier

ResourceIdentifier of a Payment. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

id​
String​

Unique identifier of the referenced Payment. Required if key is absent.

key​
String​

User-defined unique identifier of the referenced Payment. Required if id is absent.

typeId​
ReferenceTypeId​
"payment"

References a Payment.

PaymentMethodInfo

paymentInterface​
String​

Payment service that processes the Payment (for example, a PSP). Once set, it cannot be changed. The combination of paymentInterface and the interfaceId of a Payment must be unique.

method​
String​

Payment method used, for example, credit card, or cash advance.

name​
LocalizedString​

Localizable name of the payment method.

PaymentStatus

interfaceCode​
String​

External reference that identifies the current status of the Payment.

interfaceText​
String​

Text describing the current status of the Payment.

state​
StateReference​

Reference to a State.

PaymentStatusDraft

interfaceCode​
String​

External reference that identifies the current status of the Payment.

interfaceText​
String​

Text describing the current status of the Payment.

state​
StateResourceIdentifier​

ResourceIdentifier to a State.

Transaction

Represents a financial transaction typically created as a result of a notification from the payment service.

id​
String​

Unique identifier of the Transaction.

timestamp​
DateTime​

Date and time (UTC) the Transaction took place.

type​
TransactionType​

Type of the Transaction. For example, Authorization.

amount​
CentPrecisionMoney​

Money value of the Transaction.

interactionId​
String​

Identifier used by the interface that manages the Transaction (usually the PSP). If a matching interaction was logged in the interfaceInteractions array, the corresponding interaction can be found with this ID.

state​
TransactionState​

State of the Transaction.

custom​
CustomFields​

Custom Fields defined for the Transaction.

TransactionDraft

timestamp​
DateTime​

Date and time (UTC) the Transaction took place.

type​
TransactionType​

Type of the Transaction.

amount​
Money​

Money value for the Transaction.

interactionId​
String​

Identifier used by the payment service that manages the Transaction. Can be used to correlate the Transaction to an interface interaction.

state​
TransactionState​

State of the Transaction.

Default: Initial​
custom​
CustomFieldsDraft​

Custom Fields of the Transaction.

TransactionType

Authorization

Financially reliable reservation of an amount. Typically does not indicate an actual transfer of money.

CancelAuthorization

Explicit cancellation of an authorized amount before its expiry.

Charge

Collection of money from the customer. Can use an authorized amount or be directly executed.

Refund

Explicit transfer of money back to the customer.

Chargeback

Customer-initiated transfer of money back to the customer.

TransactionState

Transactions can be in one of the following States:

Initial

Initial State. The payment service has not accepted the Transaction yet.

Pending

The payment service has accepted the Transaction, but it is not completed yet.

Success

The payment service has confirmed the successful completion of the Transation.

Failure

Transaction has unrecoverably failed.

Get Payment

Get Payment by ID

GET
https://api.{region}.commercetools.com/{projectKey}/payments/{id}
OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the Payment.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Paymentasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {},
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Get Payment by Key

GET
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}
OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the Payment.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Paymentasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {},
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Query Payments

GET
https://api.{region}.commercetools.com/{projectKey}/payments
OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
​
Any string parameter matching this regular expression
​

Predicate parameter values.

The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

offset
​
Int
​

Number of elements skipped.

withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Default: true​
Response:
200PaymentPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: PaymentPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "459e32dc-74ef-4189-bbd0-932275bb027c",
      "version": 1,
      "key": "123456",
      "interfaceId": "78901",
      "amountPlanned": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "paymentMethodInfo": {
        "paymentInterface": "STRIPE",
        "method": "CREDIT_CARD",
        "name": {
          "en": "Credit Card"
        }
      },
      "paymentStatus": {},
      "transactions": [
        {
          "id": "2e318aa5-8af4-4db1-909d-e7142f7d174f",
          "timestamp": "2015-10-20T08:51:56.000Z",
          "type": "Charge",
          "amount": {
            "type": "centPrecision",
            "fractionDigits": 2,
            "currencyCode": "USD",
            "centAmount": 1000
          },
          "state": "Pending"
        }
      ],
      "interfaceInteractions": [],
      "createdAt": "2015-10-20T08:51:43.082Z",
      "lastModifiedAt": "2015-10-20T08:51:43.082Z"
    }
  ]
}

Check if Payment exists

Check if Payment exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/payments/{id}

Checks if a Payment exists for a given id. Returns a 200 OK status if the Payment exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the Payment.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Payment exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}

Checks if a Payment exists for a given key. Returns a 200 OK status if the Payment exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the Payment.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Payment exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/payments

Checks if a Payment exists for a given Query Predicate. Returns a 200 OK status if any Payments match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create Payment

POST
https://api.{region}.commercetools.com/{projectKey}/payments

Creating a Payment produces the PaymentCreated Message.

OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:PaymentDraftasapplication/json
Response:
201Paymentasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "123456",
  "interfaceId" : "789011",
  "amountPlanned" : {
    "currencyCode" : "USD",
    "centAmount" : 1000
  },
  "paymentMethodInfo" : {
    "paymentInterface" : "STRIPE",
    "method" : "CREDIT_CARD",
    "name" : {
      "en" : "Credit Card"
    }
  },
  "transactions" : [ {
    "timestamp" : "2015-10-20T08:54:24.000Z",
    "type" : "Charge",
    "amount" : {
      "currencyCode" : "USD",
      "centAmount" : 1000
    },
    "state" : "Pending"
  } ]
}
DATA
201 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {},
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Update Payment

Update Payment by ID

POST
https://api.{region}.commercetools.com/{projectKey}/payments/{id}
OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the Payment.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the Payment on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions​
Array of PaymentUpdateAction​

Update actions to be performed on the Payment.

Response:
200Paymentasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "transitionState",
    "state" : {
      "typeId" : "state",
      "id" : "18748fe6-7f77-456a-96c8-913b1e4bbc9c"
    }
  } ]
}
DATA
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {},
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Update Payment by Key

POST
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}
OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the Payment.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the Payment on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions​
Array of PaymentUpdateAction​

Update actions to be performed on the Payment.

Response:
200Paymentasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "transitionState",
    "state" : {
      "typeId" : "state",
      "id" : "18748fe6-7f77-456a-96c8-913b1e4bbc9c"
    }
  } ]
}
DATA
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {},
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Update actions

Set Key

action​
String​
"setKey"
key​
String​

Value to set. If key is absent or null, the existing key, if any, will be removed.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action": "setKey",
  "key": "String"
}

Change AmountPlanned

Can be used to update the Payment if a customer changes the Cart, or adds or removes a CartDiscount during checkout.

action​
String​
"changeAmountPlanned"
amount​
Money​

New value to set.

Example: json
{
  "action": "changeAmountPlanned",
  "amount": {
    "currencyCode": "EUR",
    "centAmount": 4000
  }
}

Set Customer

action​
String​
"setCustomer"
customer​
CustomerResourceIdentifier​

Value to set. If empty, any existing reference is removed.

Example: json
{
  "action": "setCustomer",
  "customer": {
    "typeId": "customer",
    "id": "{{customer-id}}"
  }
}

Set AnonymousId

If the Payment is already associated with a Customer, an InvalidOperation error is returned.

action​
String​
"setAnonymousId"
anonymousId​
String​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setAnonymousId",
  "anonymousId": "anonymousId"
}

Set InterfaceId

action​
String​
"setInterfaceId"
interfaceId​
String​

Value to set. Once set, the interfaceId cannot be changed.

Example: json
{
  "action": "setInterfaceId",
  "interfaceId": "InterfaceID"
}

Set MethodInfoInterface

action​
String​
"setMethodInfoInterface"
interface​
String​

Value to set. Once set, the paymentInterface of the paymentMethodInfo cannot be changed.

Example: json
{
  "action": "setMethodInfoInterface",
  "interface": "MethodInfoInterfaceString"
}

Set MethodInfoMethod

action​
String​
"setMethodInfoMethod"
method​
String​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setMethodInfoMethod",
  "method": "MethodInfoMethodString"
}

Set MethodInfoName

action​
String​
"setMethodInfoName"
name​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setMethodInfoName",
  "name": {
    "de": "MethodInfoNameStringDE",
    "en": "MethodInfoNameStringEN"
  }
}

Set StatusInterfaceCode

Produces the PaymentStatusInterfaceCodeSet Message.

action​
String​
"setStatusInterfaceCode"
interfaceCode​
String​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setStatusInterfaceCode",
  "interfaceCode": "InterfaceCodeString"
}

Set StatusInterfaceText

action​
String​
"setStatusInterfaceText"
interfaceText​
String​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setStatusInterfaceText",
  "interfaceText": "InterfaceTextString"
}

Transition State

If the Payment has no current State, initial must be true for the new State. If the existing State has transitions set, the new State must be a valid transition. If the existing State has no transitions set, no validations are performed when transitioning to the new State.

Transitioning the State of a Payment produces the PaymentStatusStateTransition Message.

action​
String​
"transitionState"
state​
StateResourceIdentifier​

ResourceIdentifier to a State.

force​
Boolean​

Set to true to skip validations when transitioning to the new State.

Default: false​
Example: json
{
  "action": "transitionState",
  "state": {
    "typeId": "state",
    "id": "{{paymentStateId}}"
  }
}

Add Transaction

Adding a Transaction to a Payment generates the PaymentTransactionAdded Message.

action​
String​
"addTransaction"
transaction​
TransactionDraft​

Value to append to the transactions array.

Example: json
{
  "action": "addTransaction",
  "transaction": {
    "type": "Authorization",
    "amount": {
      "centAmount": 4000,
      "currencyCode": "EUR"
    }
  }
}

Change TransactionState

Changing the TransactionState generates the PaymentTransactionStateChanged Message.

action​
String​
"changeTransactionState"
transactionId​
String​

Unique identifier of the Transaction.

state​
TransactionState​

New TransactionState.

Example: json
{
  "action": "changeTransactionState",
  "transactionId": "{{transactionId}}",
  "state": "Failure"
}

Change TransactionTimestamp

action​
String​
"changeTransactionTimestamp"
transactionId​
String​

Unique identifier of the Transaction.

timestamp​
DateTime​

Timestamp of the Transaction as reported by the payment service.

Example: json
{
  "action": "changeTransactionTimestamp",
  "transactionId": "{{transactionId}}",
  "timestamp": "2018-10-12T14:00:00.000Z"
}

Change TransactionInteractionId

action​
String​
"changeTransactionInteractionId"
transactionId​
String​

Unique identifier of the Transaction.

interactionId​
String​

New value to set.

Example: json
{
  "action": "changeTransactionInteractionId",
  "transactionId": "{{transactionId}}",
  "interactionId": "{{newInteractionId}}"
}

Add InterfaceInteraction

Adding a Payment interaction generates the PaymentInteractionAdded Message.

action​
String​
"addInterfaceInteraction"
type​
TypeResourceIdentifier​

ResourceIdentifier of a Type.

fields​
FieldContainer​

Custom Fields as per FieldDefinitions of the Type.

Example: json
{
  "action": "addInterfaceInteraction",
  "type": {
    "typeId": "type",
    "id": "{{type-id}}"
  }
}

Set Custom Type

action​
String​
"setCustomType"
type​
TypeResourceIdentifier​

Defines the Type that extends the Payment with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Payment.

fields​
FieldContainer​

Sets the Custom Fields fields for the Payment.

Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

action​
String​
"setCustomField"
name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action": "setCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Set Transaction Custom Type

action​
String​
"setTransactionCustomType"
transactionId​
String​

Unique identifier of the Transaction. If the specified transactionId does not exist, the request will fail with an InvalidOperation error.

type​
TypeResourceIdentifier​

Defines the Type that extends the Transaction with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Transaction.

fields​
FieldContainer​

Sets the Custom Fields fields for the Transaction.

Example: json
{
  "action": "setTransactionCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  },
  "transactionId": "transactionIdTest"
}

Set Transaction CustomField

action​
String​
"setTransactionCustomField"
transactionId​
String​

Unique identifier of the Transaction.

name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action": "setTransactionCustomField",
  "name": "exampleStringField",
  "value": "TextString",
  "transactionId": "transactionIdTest"
}

Delete Payment

Delete Payment by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/payments/{id}
OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the Payment.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
dataErasure
​
Boolean
​

To erase all related personal data in compliance with GDPR, set to true.

Default: false​
Response:
200Paymentasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/payments/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {},
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Delete Payment by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}
OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the Payment.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
dataErasure
​
Boolean
​

To erase all related personal data in compliance with GDPR, set to true.

Default: false​
Response:
200Paymentasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/payments/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {},
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}