1 July 2025
Composable Commerce
HTTP API
New feature
PaymentsSecurity and privacyMessages/SubscriptionsLimitsGraphQL
With the introduction of the Payment Methods API, integration with external Payment Service Providers (PSPs) becomes seamless. It simplifies payment flows by providing a reusable, structured model to store customers' payment details, such as PSP-related metadata, the specific payment method used, and the payment token required for transaction processing.
The API is available in public beta.

Changes:

  • [API] Added the Payment Methods API.
  • [API] Added view_payment_methods:{projectKey} and manage_payment_methods:{projectKey} OAuth scopes.
  • [API] Added the Payment Method Messages.
  • [API] Updated the following in the Payments API:
  • [API] Updated the following in the My Payments API:
  • [API] Added the following Messages for Payments: PaymentInterfaceIdSet, PaymentMethodInfoInterfaceSet, PaymentMethodInfoMethodSet, PaymentMethodInfoNameSet, PaymentMethodInfoCustomFieldAdded, PaymentMethodInfoCustomFieldChanged, PaymentMethodInfoCustomFieldRemoved, PaymentMethodInfoCustomTypeSet, PaymentMethodInfoCustomTypeRemoved, PaymentMethodInfoInterfaceAccountSet, and PaymentMethodInfoTokenSet.
  • [GraphQL API] Added the following types to the GraphQL schema: PaymentInterfaceIdSet, PaymentMethod, PaymentMethodCreated, PaymentMethodCustomFieldAdded, PaymentMethodCustomFieldChanged, PaymentMethodCustomFieldRemoved, PaymentMethodCustomTypeRemoved, PaymentMethodCustomTypeSet, PaymentMethodDefaultSet, PaymentMethodDeleted, PaymentMethodDraft, PaymentMethodInfoCustomFieldAdded, PaymentMethodInfoCustomFieldChanged, PaymentMethodInfoCustomFieldRemoved, PaymentMethodInfoCustomTypeRemoved, PaymentMethodInfoCustomTypeSet, PaymentMethodInfoInterfaceAccountSet, PaymentMethodInfoInterfaceSet, PaymentMethodInfoMethodSet, PaymentMethodInfoNameSet, PaymentMethodInfoTokenSet, PaymentMethodInterfaceAccountSet, PaymentMethodKeySet, PaymentMethodMethodSet, PaymentMethodNameSet, PaymentMethodPaymentInterfaceSet, PaymentMethodQueryResult, PaymentMethodStatus, PaymentMethodPaymentMethodStatusSet, PaymentMethodToken, PaymentMethodTokenDraft, PaymentMethodUpdateAction, SetPaymentMethodCustomField, SetPaymentMethodCustomType, SetPaymentMethodDefault, SetPaymentMethodInfo, SetPaymentMethodInfoCustomField, SetPaymentMethodInfoCustomType, SetPaymentMethodInfoInterfaceAccount, SetPaymentMethodInfoToken, SetPaymentMethodInterfaceAccount, SetPaymentMethodKey, SetPaymentMethodMethod, SetPaymentMethodName, SetPaymentMethodPaymentInterface, and SetPaymentMethodStatus.
  • [GraphQL API] Added the paymentMethod and paymentMethods field to the Query type.
  • [GraphQL API] Added the createPaymentMethod, updatePaymentMethod, and deletePaymentMethod fields to the Mutation type.
  • [GraphQL API] Added the setMethodInfo, setMethodInfoInterfaceAccount, setMethodInfoToken, setMethodInfoCustomType, and setMethodInfoCustomField input fields to the PaymentUpdateAction type.
  • [GraphQL API] Added the setMethodInfoInterfaceAccount, setMethodInfoCustomType, and setMethodInfoCustomField input fields to the MyPaymentUpdateAction type.
  • [GraphQL API] Added the token, interfaceAccount, and custom fields to the PaymentMethodInfo type.
  • [GraphQL API] Added the token, interfaceAccount, and custom input fields to the PaymentMethodInfoInput type.

The following changes were introduced in terms of GraphQL SDL:

extend type Query {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  paymentMethod(
    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): PaymentMethod

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  paymentMethods(where: String, sort: [String!], limit: Int, offset: Int): PaymentMethodQueryResult!
}

extend type Mutation {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  createPaymentMethod(draft: PaymentMethodDraft!): PaymentMethod

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  deletePaymentMethod(version: Long!, personalDataErasure: Boolean = false,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): PaymentMethod

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  updatePaymentMethod(version: Long!, actions: [PaymentMethodUpdateAction!]!,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): PaymentMethod
}

extend type PaymentMethodInfo {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  custom: CustomFieldsType

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  interfaceAccount: String

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  token: PaymentMethodToken
}

extend input PaymentMethodInfoInput {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  custom: CustomFieldsDraft

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  interfaceAccount: String

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  token: PaymentMethodTokenDraft
}

extend input MyPaymentUpdateAction {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfoCustomField: SetPaymentMethodInfoCustomField

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfoCustomType: SetPaymentMethodInfoCustomType

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfoInterfaceAccount: SetPaymentMethodInfoInterfaceAccount
}

extend input PaymentUpdateAction {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfo: SetPaymentMethodInfo

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfoCustomField: SetPaymentMethodInfoCustomField

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfoCustomType: SetPaymentMethodInfoCustomType

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfoInterfaceAccount: SetPaymentMethodInfoInterfaceAccount

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMethodInfoToken: SetPaymentMethodInfoToken
}

type PaymentInterfaceIdSet implements MessagePayload {
  interfaceId: String
  oldInterfaceId: String
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type PaymentMethod implements Versioned & ReferenceExpandable {
  key: String
  name(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  nameAllLocales: [LocalizedString!]
  customer: Customer
  customerRef: Reference
  businessUnit: BusinessUnit
  businessUnitRef: KeyReference
  token: PaymentMethodToken
  method: String
  paymentInterface: String
  interfaceAccount: String
  paymentMethodStatus: PaymentMethodStatus!
  default: Boolean!
  custom: CustomFieldsType
  id: String!
  version: Long!
  createdAt: DateTime!
  lastModifiedAt: DateTime!
  createdBy: Initiator
  lastModifiedBy: Initiator
}

type PaymentMethodCreated implements MessagePayload {
  paymentMethod: PaymentMethod!
  type: String!
}

type PaymentMethodCustomFieldAdded implements MessagePayload {
  name: String!
  value: Json!
  type: String!
}

type PaymentMethodCustomFieldChanged implements MessagePayload {
  name: String!
  value: Json!
  oldValue: Json
  type: String!
}

type PaymentMethodCustomFieldRemoved implements MessagePayload {
  name: String!
  type: String!
}

type PaymentMethodCustomTypeRemoved implements MessagePayload {
  oldTypeId: String
  type: String!
}

type PaymentMethodCustomTypeSet implements MessagePayload {
  customFields: CustomFieldsType!
  oldTypeId: String
  type: String!
}

type PaymentMethodDefaultSet implements MessagePayload {
  default: Boolean!
  oldDefault: Boolean!
  type: String!
}

type PaymentMethodDeleted implements MessagePayload {
  paymentMethod: PaymentMethod!
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input PaymentMethodDraft {
  key: String
  name: [LocalizedStringItemInputType!]
  customer: ResourceIdentifierInput
  businessUnit: ResourceIdentifierInput
  token: PaymentMethodTokenDraft
  method: String
  paymentInterface: String
  interfaceAccount: String
  paymentMethodStatus: PaymentMethodStatus
  default: Boolean
  custom: CustomFieldsDraft
}

type PaymentMethodInfoCustomFieldAdded implements MessagePayload {
  name: String!
  value: Json!
  type: String!
}

type PaymentMethodInfoCustomFieldChanged implements MessagePayload {
  name: String!
  value: Json!
  type: String!
}

type PaymentMethodInfoCustomFieldRemoved implements MessagePayload {
  name: String!
  type: String!
}

type PaymentMethodInfoCustomTypeRemoved implements MessagePayload {
  oldTypeId: String
  type: String!
}

type PaymentMethodInfoCustomTypeSet implements MessagePayload {
  customFields: CustomFieldsType!
  oldTypeId: String
  type: String!
}

type PaymentMethodInfoInterfaceAccountSet implements MessagePayload {
  interfaceAccount: String
  oldInterfaceAccount: String
  type: String!
}

type PaymentMethodInfoInterfaceSet implements MessagePayload {
  interface: String
  oldInterface: String
  type: String!
}

type PaymentMethodInfoMethodSet implements MessagePayload {
  method: String
  oldMethod: String
  type: String!
}

type PaymentMethodInfoNameSet implements MessagePayload {
  nameAllLocales: [LocalizedString!]
  oldNameAllLocales: [LocalizedString!]
  name(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  oldName(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  type: String!
}

type PaymentMethodInfoTokenSet implements MessagePayload {
  token: PaymentMethodToken
  oldToken: PaymentMethodToken
  type: String!
}

type PaymentMethodInterfaceAccountSet implements MessagePayload {
  interfaceAccount: String
  oldInterfaceAccount: String
  type: String!
}

type PaymentMethodKeySet implements MessagePayload {
  key: String
  oldKey: String
  type: String!
}

type PaymentMethodMethodSet implements MessagePayload {
  method: String
  oldMethod: String
  type: String!
}

type PaymentMethodNameSet implements MessagePayload {
  nameAllLocales: [LocalizedString!]
  oldNameAllLocales: [LocalizedString!]
  name(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  oldName(
    "String is defined for different locales. This argument specifies the desired locale."
    locale: Locale,

    "List of languages the client is able to understand, and which locale variant is preferred."
    acceptLanguage: [Locale!]): String
  type: String!
}

type PaymentMethodPaymentInterfaceSet implements MessagePayload {
  paymentInterface: String
  oldPaymentInterface: String
  type: String!
}

type PaymentMethodQueryResult {
  offset: Int!
  count: Int!
  total: Long!
  exists: Boolean!
  results: [PaymentMethod!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum PaymentMethodStatus {
  Active
  Inactive
}

type PaymentMethodPaymentMethodStatusSet implements MessagePayload {
  status: PaymentMethodStatus!
  oldStatus: PaymentMethodStatus!
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type PaymentMethodToken {
  value: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input PaymentMethodTokenDraft {
  value: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input PaymentMethodUpdateAction {
  setCustomField: SetPaymentMethodCustomField
  setCustomType: SetPaymentMethodCustomType
  setDefault: SetPaymentMethodDefault
  setInterfaceAccount: SetPaymentMethodInterfaceAccount
  setKey: SetPaymentMethodKey
  setMethod: SetPaymentMethodMethod
  setName: SetPaymentMethodName
  setPaymentInterface: SetPaymentMethodPaymentInterface
  setPaymentMethodStatus: SetPaymentMethodStatus
}

input SetPaymentMethodCustomField {
  name: String!
  value: String
}

input SetPaymentMethodCustomType {
  fields: [CustomFieldInput!]
  type: ResourceIdentifierInput
  typeKey: String
  typeId: String
}

input SetPaymentMethodDefault {
  default: Boolean!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetPaymentMethodInfo {
  paymentInterface: String
  method: String
  name: [LocalizedStringItemInputType!]
  token: PaymentMethodTokenDraft
  interfaceAccount: String
  custom: CustomFieldsDraft
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetPaymentMethodInfoCustomField {
  name: String!
  value: String
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetPaymentMethodInfoCustomType {
  fields: [CustomFieldInput!]
  type: ResourceIdentifierInput
  typeKey: String
  typeId: String
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetPaymentMethodInfoInterfaceAccount {
  interfaceAccount: String
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetPaymentMethodInfoToken {
  token: PaymentMethodTokenDraft
}

input SetPaymentMethodInterfaceAccount {
  interfaceAccount: String
}

input SetPaymentMethodKey {
  key: String
}

input SetPaymentMethodMethod {
  method: String
}

input SetPaymentMethodName {
  name: [LocalizedStringItemInputType!]
}

input SetPaymentMethodPaymentInterface {
  paymentInterface: String
}

input SetPaymentMethodStatus {
  paymentMethodStatus: PaymentMethodStatus!
}