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 payment service provider, which is connected to Composable Commerce by PSP-specific integrations.

Representations

Payment

PaymentDraft

PaymentPagedQueryResponse

PaymentReference

PaymentResourceIdentifier

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	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the Payment was last updated.
`lastModifiedBy`BETA LastModifiedBy	Present on resources created after 1 February 2019 except for events not tracked.

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

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

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

`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": {
    "exampleStringTypeField": "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": "ExampleStringTypeField",
  "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": {
    "exampleStringTypeField": "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": "ExampleStringTypeField",
  "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	Defaults to `false`. Set to `true` if you want to erase all related personal data in compliance with GDPR.

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	Defaults to `false`. Set to `true` if you want to erase all related personal data in compliance with GDPR.

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

Payments

Representations

Payment

PaymentDraft

PaymentPagedQueryResponse

PaymentReference

PaymentResourceIdentifier

PaymentMethodInfo

PaymentStatus

PaymentStatusDraft

Transaction

TransactionDraft

TransactionType

TransactionState

Get Payment

Get Payment by ID

Get Payment by Key

Query Payments

Check if Payment exists

Check if Payment exists by ID

Check if Payment exists by Key

Check if Payment exists by Query Predicate

Create Payment

Update Payment

Update Payment by ID

Update Payment by Key

Update actions

Set Key

Change AmountPlanned

Set Customer

Set AnonymousId

Set InterfaceId

Set MethodInfoInterface

Set MethodInfoMethod

Set MethodInfoName

Set StatusInterfaceCode

Set StatusInterfaceText

Transition State

Add Transaction

Change TransactionState

Change TransactionTimestamp

Change TransactionInteractionId

Add InterfaceInteraction

Set Custom Type

Set CustomField

Set Transaction Custom Type

Set Transaction CustomField

Delete Payment

Delete Payment by ID

Delete Payment by Key