A payment represents one or a logically connected series of financial transactions like reserving money, charging money or refunding money. They serve as a representation of the current state of the payment and can also be used to trigger new transactions. The actual financial process is not done by the commercetools platform but usually by a PSP (Payment Service Provider), which is connected via PSP-specific integration implementation. The Payment representation does not contain payment method-specific fields. These are added as CustomFields via a payment method-specific payment type.
Payments are usually referenced by an order or a cart in their PaymentInfo Object. They usually reference a Customer, unless they are part of an anonymous order.
User-specific unique identifier for the payment (max. 256 characters).
The identifier that is used by the interface that manages the payment (usually the PSP). Cannot be changed once it has been set. The combination of this ID and the PaymentMethodInfo paymentInterface must be unique.
Interface interactions can be requests sent to the PSP, responses received from the PSP or notifications received from the PSP. Some interactions may result in a transaction. If so, the interactionId in the Transaction should be set to match the ID of the PSP for the interaction. Interactions are managed by the PSP integration and are usually neither written nor read by the user facing frontends or other services.
A list of financial transactions of different TransactionTypes with different TransactionStates.
Interface interactions can be requests send to the PSP, responses received from the PSP or notifications received from the PSP. Some interactions may result in a transaction. If so, the interactionId in the Transaction should be set to match the ID of the PSP for the interaction. Interactions are managed by the PSP integration and are usually neither written nor read by the user facing frontends or other services.
The interface that handles the payment (usually a PSP). Cannot be changed once it has been set. The combination of PaymentinterfaceId and this field must be unique.
The payment method that is used, e.g. e.g. a conventional string representing Credit Card, Cash Advance etc.
A human-readable, localized name for the payment method, e.g. ‘Credit Card’.
A code describing the current status returned by the interface that processes the payment.
A text describing the current status returned by the interface that processes the payment.
A representation of a financial transaction. Transactions are either created by the solution implementation to trigger a new transaction at the PSP or created by the PSP integration as the result of a notification by the PSP.
The unique ID of this object.
The type of this transaction.
The state of this transaction.
The state of this transaction. If not set, defaults to Initial.
Authorization - A financially reliable reservation of the amount that does not yet trigger an actual money transfer.
CancelAuthorization - Explicit cancellation of an authorized amount before it is expiring.
Charge - Collection of money from the customer. Can use an authorized amount or be directly executed.
Refund - Explicit transfer of money back to the customer.
Chargeback - Customer-triggered transfer of money back to the customer.
Initial - The initial state. The PSP has not accepted the transaction yet (this includes if the PSP has not been contacted yet).
Pending - The PSP has accepted the transaction, but it is not completed yet.
Success - Transactions should only be set to state Success after a confirmation from the PSP was received that confirms that a transaction was completed successfully. E.g. in the case of a refund, the transaction is not added when the refund request is being sent to the PSP or the PSP acknowledges the request (the interfaceInteractions may be used for these), but when the PSP sends a notification that the refund has been executed.
Failure - The transaction has unrecoverably failed.
To create a payment object a payment draft object has to be given with the request.
The expected version of the payment resource on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
User-specific unique identifier for the payment (max. 256 characters). If not provided an existing key will be removed.
Changes how much money this payment intends to receive from the customer. The value usually matches the cart or order gross total. Updating the amountPlanned may be required after a customer changed the cart or added/removed a CartDiscount during the checkout.
action - String - "changeAmountPlanned"
Sets the reference to the customer. If not defined, the reference is unset.
Sets an anonymous ID that corresponds to a customer who has authenticated with an anonymous session.
Anonymous ID of the anonymous customer that this payment belongs to. If this field is not set any existing anonymousId is removed.
Sets the identifier that is used by the interface that manages the payment (usually the PSP). Cannot be changed once it has been set. The combination of interfaceId and PaymentMethodInfo paymentInterface must be unique.
action - String - "setInterfaceId"
Sets the interface that handles the payment (usually a PSP). Cannot be changed once it has been set. The combination of Payment interfaceId and PaymentMethodInfo paymentInterface must be unique.
action - String - "setMethodInfoInterface"
Sets the method used, e.g. a conventional string representing Credit Card or Cash Advance.
action - String - "setMethodInfoMethod"
If not provided, the method is unset.
Sets a human-readable, localizable name for the payment method, e.g. ‘Credit Card’.
action - String - "setMethodInfoName"
If not provided, the name is unset.
Sets the code, given by the PSP, that describes the current status.
action - String - "setStatusInterfaceCode"
Setting the status interface code produces the PaymentStatusInterfaceCodeSet message.
Sets a text, given by the PSP, that describes the current status.
action - String - "setStatusInterfaceText"
Transition to a new state. If there is no state yet, the new state must be an initial state. If the existing state has transitions set, there must be a direct transition to the new state. If transitions is not set, no validation is performed. These validations can be turned off by setting the force parameter to true.
Transitioning the state of a payment produces the PaymentStatusStateTransition message.
Adds a new financial transaction. It can be used for asynchronous communication, e.g. one process could add a transaction of type Refund in state Initial and a PSP integration could asynchronously take care of executing the refund.
Changes state of a transaction. If a transaction has been executed asynchronously, it’s state can be updated. E.g. if a Refund was executed, the state can be set to Success.
action - String - "changeTransactionState"
state - TransactionState - The new state of this transaction.
Changes timestamp of a transaction. If this transaction represents an action at the PSP, the time returned by the PSP should be used.
action - String - "changeTransactionTimestamp"
timestamp - DateTime - The new timestamp.
Changes the interactionId of a transaction. It should correspond to an ID of an interface interaction.
action - String - "changeTransactionInteractionId"
interactionId - String - The new interactionId.
Adds a new interaction with the interface. These can be notifications received from the PSP or requests send to the PSP. Some interactions may result in a transaction. If so, the interactionId in the transaction should be set to match the ID of the PSP for the interaction.
action - String - "addInterfaceInteraction"
This action sets, overwrites or removes any existing custom type and fields for an existing payment.
Sets the custom fields to this value.
This action sets, overwrites or removes any existing custom field for an existing payment.