1 July 2025
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}andmanage_payment_methods:{projectKey}OAuth scopes. - [API] Added the Payment Method Messages.
 - [API] Updated the following in the Payments API:
- Added the 
token,interfaceAccount, andcustomfields to the PaymentMethodInfo type. - Added the PaymentMethodInfoDraft type.
 - Updated the PaymentDraft 
paymentMethodInfofield type to PaymentMethodInfoDraft. - Added the following update actions: Set MethodInfo, Set MethodInfo InterfaceAccount, Set MethodInfo Token, Set MethodInfo Custom Type, and Set MethodInfo CustomField.
 
 - Added the 
 - [API] Updated the following in the My Payments API:
- Updated the MyPaymentDraft 
paymentMethodInfofield type to PaymentMethodInfoDraft. - Added the following update actions: Set MethodInfo InterfaceAccount, Set MethodInfo Custom Type and Set MethodInfo CustomField.
 
 - Updated the MyPaymentDraft 
 - [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, andSetPaymentMethodStatus. - [GraphQL API] Added the 
paymentMethodandpaymentMethodsfield to theQuerytype. - [GraphQL API] Added the 
createPaymentMethod,updatePaymentMethod, anddeletePaymentMethodfields to theMutationtype. - [GraphQL API] Added the 
setMethodInfo,setMethodInfoInterfaceAccount,setMethodInfoToken,setMethodInfoCustomType, andsetMethodInfoCustomFieldinput fields to thePaymentUpdateActiontype. - [GraphQL API] Added the 
setMethodInfoInterfaceAccount,setMethodInfoCustomType, andsetMethodInfoCustomFieldinput fields to theMyPaymentUpdateActiontype. - [GraphQL API] Added the 
token,interfaceAccount, andcustomfields to thePaymentMethodInfotype. - [GraphQL API] Added the 
token,interfaceAccount, andcustominput fields to thePaymentMethodInfoInputtype. 
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!
}