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