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
, andcustom
fields to the PaymentMethodInfo type. - Added the PaymentMethodInfoDraft type.
- Updated the PaymentDraft
paymentMethodInfo
field 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
paymentMethodInfo
field 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
paymentMethod
andpaymentMethods
field to theQuery
type. - [GraphQL API] Added the
createPaymentMethod
,updatePaymentMethod
, anddeletePaymentMethod
fields to theMutation
type. - [GraphQL API] Added the
setMethodInfo
,setMethodInfoInterfaceAccount
,setMethodInfoToken
,setMethodInfoCustomType
, andsetMethodInfoCustomField
input fields to thePaymentUpdateAction
type. - [GraphQL API] Added the
setMethodInfoInterfaceAccount
,setMethodInfoCustomType
, andsetMethodInfoCustomField
input fields to theMyPaymentUpdateAction
type. - [GraphQL API] Added the
token
,interfaceAccount
, andcustom
fields to thePaymentMethodInfo
type. - [GraphQL API] Added the
token
,interfaceAccount
, andcustom
input fields to thePaymentMethodInfoInput
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!
}