Queries and mutations for managing Payments in the platform.

Queries

Query Payments

QUERYpayments
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get Payment

QUERYpayment
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Payment

Mutations

Create Payment

MUTATIONcreatePayment
Arguments
draft​
Output:Payment

Update Payment

MUTATIONupdatePayment
Arguments
version​
Long​
actions​
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Payment

Delete Payment

MUTATIONdeletePayment
Arguments
version​
Long​
personalDataErasure​
Boolean​
Default: false​
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Payment

Output types

Payment

Payments hold information about the current state of receiving and/or refunding money. documentation
key​
String​

User-defined unique identifier of the Payment.

customerRef​
Reference to a Customer associated with the Payment.
customer​
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​
Money value the Payment intends to receive from the customer. The value typically matches the Cart or Order gross total.
paymentMethodInfo​

Information regarding the payment interface (for example, a PSP), and the specific payment method used.

paymentStatus​

Current status of the Payment.

transactions​
Array of Transaction​
Financial transactions of the Payment. Each Transaction has a TransactionType and a TransactionState.
interfaceInteractionsRaw​

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​

Custom Fields of the Payment.

id​
String​

Unique identifier of the Payment.

version​
Long​

Current version of the Payment.

createdAt​

Date and time (UTC) the Payment was initially created.

lastModifiedAt​

Date and time (UTC) the Payment was last updated.

createdBy​

IDs and references that created the Payment.

lastModifiedBy​

IDs and references that last modified the Payment.

PaymentMethodInfo

Represents a snapshot of the PaymentMethod data used for a Payment.

paymentInterface​
String​
Payment service that processes the Payment—for example, a PSP. The combination of paymentInterface and the interfaceId of a Payment is unique.
method​
String​

Payment method used—for example, a credit card or direct debit.

name​
String​

Name of the Payment Method.

nameAllLocales​
Array of LocalizedString​

Name of the Payment Method.

token​
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
custom​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta

PaymentMethodToken

value​
String​

Tokenized representation of the Payment Method.

It is displayed in the following instances:
  • in the payload of an API Extension for Payments and PaymentMethods
  • when querying Payments and PaymentMethods
It is masked in the following instances:
  • in the payload of Payment and PaymentMethod messages
  • when querying MyPayments
  • in referenced Payments and PaymentMethods embedded through Reference Expansion

PaymentStatus

interfaceCode​
String​

External reference that identifies the current status of the Payment.

interfaceText​
String​

Text describing the current status of the Payment.

stateRef​
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​

Date and time (UTC) the Transaction took place.

type​
Type of the Transaction. For example, Authorization.
Can be Authorization, CancelAuthorization, Charge, Chargeback, or Refund​
amount​

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​

State of the Transaction.

Can be Failure, Initial, Pending, or Success​
custom​

Custom Fields defined for the Transaction.

interfaceId​
String​

Identifier used by the payment service that processes the Payment (for example, a PSP) in the current transaction.

TransactionType

Authorization
CancelAuthorization
Charge
Chargeback
Refund

TransactionState

Failure
Initial
Pending
Success

InterfaceInteractionsRawResult

limit​
Int​
offset​
Int​
total​
Int​
results​

InterfaceInteractionsRaw

typeRef​
type​
fields​
Array of RawCustomField​

Payment Query Result

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of Payment​

Input types

PaymentDraft

amountPlanned​
Money value the Payment intends to receive from the customer. The value typically matches the Cart or Order gross total.
paymentMethodInfo​

Information regarding the payment interface (for example, a PSP), and the specific payment method used.

custom​

Custom Fields for the Payment.

key​
String​

User-defined unique identifier for the Payment.

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.
paymentStatus​

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.

MoneyInput

currencyCode​
centAmount​
Long​

PaymentMethodInfoInput

paymentInterface​
String​
method​
String​
name​
token​
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
custom​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta

PaymentMethodTokenDraft

value​
String​

PaymentStatusInput

interfaceCode​
String​
interfaceText​
String​

TransactionDraft

timestamp​

Date and time (UTC) the Transaction took place.

type​

Type of the Transaction.

Can be Authorization, CancelAuthorization, Charge, Chargeback, or Refund​
amount​

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​

State of the Transaction.

Can be Failure, Initial, Pending, or Success​
custom​

Custom Fields for the Transaction.

interfaceId​
String​

Identifier used by the payment service that processes the Payment (for example, a PSP) in the current transaction.

TransactionType

Authorization
CancelAuthorization
Charge
Chargeback
Refund

TransactionState

Failure
Initial
Pending
Success

PaymentUpdateAction

addInterfaceInteraction​
addTransaction​
changeAmountPlanned​
changeTransactionInteractionId​
changeTransactionState​
changeTransactionTimestamp​
setAmountPaid​
setAmountRefunded​
setAnonymousId​
setAuthorization​
setCustomField​
setCustomType​
setCustomer​
setExternalId​
setInterfaceId​
setKey​
setMethodInfo​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
setMethodInfoCustomField​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
setMethodInfoCustomType​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
setMethodInfoInterface​
setMethodInfoInterfaceAccount​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
setMethodInfoMethod​
setMethodInfoName​
setMethodInfoToken​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
setStatusInterfaceCode​
setStatusInterfaceText​
setTransactionCustomField​
setTransactionCustomType​
setTransactionInterfaceId​
transitionState​

Update actions

Add InterfaceInteraction

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Add Transaction

Adding a Transaction to a Payment generates the PaymentTransactionAdded Message.
transaction​
Value to append to the transactions array.

TransactionDraft

timestamp​

Date and time (UTC) the Transaction took place.

type​

Type of the Transaction.

Can be Authorization, CancelAuthorization, Charge, Chargeback, or Refund​
amount​

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​

State of the Transaction.

Can be Failure, Initial, Pending, or Success​
custom​

Custom Fields for the Transaction.

interfaceId​
String​

Identifier used by the payment service that processes the Payment (for example, a PSP) in the current transaction.

TransactionType

Authorization
CancelAuthorization
Charge
Chargeback
Refund

MoneyInput

currencyCode​
centAmount​
Long​

TransactionState

Failure
Initial
Pending
Success

Change AmountPlanned

Can be used to update the Payment if a customer changes the Cart, or adds or removes a CartDiscount during checkout.
amount​

New value to set.

MoneyInput

currencyCode​
centAmount​
Long​

Change TransactionInteractionId

transactionId​
String​
Unique identifier of the Transaction.
interactionId​
String​

New value to set.

Change TransactionState

Changing the TransactionState generates the PaymentTransactionStateChanged Message.
transactionId​
String​
Unique identifier of the Transaction.
state​

New TransactionState.

Can be Failure, Initial, Pending, or Success​

TransactionState

Failure
Initial
Pending
Success

Change TransactionTimestamp

transactionId​
String​
Unique identifier of the Transaction.
timestamp​

Timestamp of the Transaction as reported by the payment service.

Set AmountPaid

amount​

MoneyInput

currencyCode​
centAmount​
Long​

Set AmountRefunded

amount​

MoneyInput

currencyCode​
centAmount​
Long​

Set AnonymousId

If the Payment is already associated with a Customer, an InvalidOperation error is returned.
anonymousId​
String​

Value to set. If omitted, any existing value is removed.

Set Authorization

amount​
until​

MoneyInput

currencyCode​
centAmount​
Long​

Set CustomField

name​
String​
Name of the Custom Field.
value​
String​
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.

Set Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Customer

Value to set. If omitted, any existing reference is removed.

Set ExternalId

externalId​
String​

Set InterfaceId

This action generates the PaymentInterfaceIdSet Message.
interfaceId​
String​
Value to set. The combination of interfaceId and paymentInterface of a PaymentMethodInfo must be unique.

The value cannot be modified after it is set.

Set Key

key​
String​
Value to set. If key is absent or null, the existing key, if any, will be removed.

Set MethodInfo BETA

BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
paymentInterface​
String​
Payment service that processes the Payment—for example, a PSP. The combination of paymentInterface and the interfaceId of a Payment must be unique. The value cannot be modified after it is set.
Setting this field is equivalent to the setMethodInfoInterface action and will generate the PaymentMethodInfoInterfaceSet Message.
method​
String​

Payment method to use—for example, a credit card or direct debit. If omitted, any existing value is removed.

Setting this field is equivalent to the setMethodInfoMethod action and will generate the PaymentMethodInfoMethodSet Message.
name​

Name of the Payment Method. If omitted, any existing value is removed.

Setting this field is equivalent to the setMethodInfoName action and will generate the PaymentMethodInfoNameSet Message.
token​

Tokenized payment method information of the Payment Method. If omitted, any existing value is removed.

Setting this field is equivalent to the setMethodInfoToken action and will generate the PaymentMethodInfoTokenSet Message.
interfaceAccount​
String​

Account or instance of the payment interface when multiple accounts are used (per interface). If omitted, any existing value is removed.

Setting this field is equivalent to the setMethodInfoInterfaceAccount action and will generate the PaymentMethodInfoInterfaceAccountSet Message.
custom​

Custom Fields for the PaymentMethodInfo. If omitted, any existing Custom Fields are removed, including the Custom Type.

Setting this field is equivalent to the setMethodInfoCustomType and setMethodInfoCustomField actions, and will generate the following Messages:

PaymentMethodTokenDraft

value​
String​

Set MethodInfo CustomField BETA

BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. If value is provided, it is set for the field defined by name. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set MethodInfo Custom Type BETA

BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set MethodInfo Interface

This action generates the PaymentMethodInfoInterfaceSet Message.
interface​
String​
Value to set. Once set, the paymentInterface of the paymentMethodInfo cannot be changed.

Set MethodInfo InterfaceAccount BETA

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​

New account or instance of the payment interface. If omitted, any existing value is removed.

Set MethodInfo Method

This action generates the PaymentMethodInfoMethodSet Message.
method​
String​

Value to set. If omitted, any existing value is removed.

Set MethodInfo Name

This action generates the PaymentMethodInfoNameSet Message.
name​

Value to set. If omitted, any existing value is removed.

Set MethodInfo Token BETA

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

Value to set. If omitted, any existing value is removed.

PaymentMethodTokenDraft

value​
String​

Set StatusInterfaceCode

Produces the PaymentStatusInterfaceCodeSet Message.
interfaceCode​
String​

Value to set. If omitted, any existing value is removed.

Set StatusInterfaceText

interfaceText​
String​

Value to set. Set to an empty string to remove any existing value.

Set Transaction CustomField

name​
String​
Name of the Custom Field.
value​
String​
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.
transactionId​
String​
Unique identifier of the Transaction.

Set Transaction Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​
transactionId​
String​

Set TransactionInterfaceId

Setting the transaction interface ID produces the PaymentTransactionInterfaceIdSet Message.
transactionId​
String​
Unique identifier of the Transaction.
interfaceId​
String​
Identifier used by the payment service that processes the Payment (for example, a PSP) in the current transaction. It must be unique across all transactions. If interfaceId is absent, this field will be removed from the specified Transaction, if it exists.

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.
force​
Boolean​

Whether to skip validations when transitioning to the new State.

Default: false​