This feature is marked as beta and may be affected by changes. Use with caution for production.

Payments

Payments hold information about the current state of receiving and/or refunding money

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.

Representations

Payment

PaymentDraft

PaymentMethodInfo

PaymentStatus

Transaction

A representation of a financial transactions. 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.

TransactionDraft

TransactionType

Not all payment methods support all of the following defined types:

TransactionState

Transactions can be in one of the following states:

Get Payment by ID

Endpoint: /{projectKey}/payments/{id}
Method: GET
OAuth2 Scopes: view_payments:{projectKey}
Response Representation: Payment

Query Payments

Endpoint: /{projectKey}/payments
Method: GET
OAuth2 Scopes: view_payments:{projectKey}
Response Representation: Payments List
Query Parameters:

Payments List

Create a Payment

To create a payment object a payment draft object has to be given with the request.

Endpoint: /{projectKey}/payments
Method: POST
OAuth2 Scopes: manage_payments:{projectKey}
Request Representation: PaymentDraft
Response Representation: Payment

Update Payment

Endpoint: /{projectKey}/payments/{id}
Method: POST
OAuth2 Scopes: manage_payments:{projectKey}
Response Representation: Payment

Update Actions
Please find below the individual update actions provided on this endpoint.


Set Key

Change AmountPlanned

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.

Set Customer

Sets the reference to the customer. If not defined, the reference is unset.

Set ExternalId

Sets a user-defined ID which can be used as additional identifier for external systems, like the systems involved in order or receivables management. If not defined, the external ID is unset.

Set InterfaceId

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.

Set Authorization

Sets the amount of money that has been authorized and optionally until when the authorization is valid.

Set AmountPaid

Sets the amount of money that has been paid by the customer.

Set AmountRefunded

Sets the amount of money that has been refunded to the customer.

Set MethodInfoInterface

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.

Set MethodInfoMethod

Sets the method used, e.g. a conventional string representing Credit Card or Cash Advance.

Set MethodInfoName

Sets a human-readable, localizable name for the payment method, e.g. ‘Credit Card’.

Set StatusInterfaceCode

Sets the code, given by the PSP, that describes the current status.

Setting the status interface code produces the PaymentStatusInterfaceCodeSet message.

Set StatusInterfaceText

Sets a text, given by the PSP, that describes the current status.

Transition State

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.

Add Transaction

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 Pending and a PSP integration could asynchronously take care of executing the refund.

Change TransactionState

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.

Change TransactionTimestamp

Changes timestamp of a transaction. If this transaction represents an action at the PSP, the time returned by the PSP should be used.

Change TransactionInteractionId

Changes the interactionId of a transaction. It should correspond to an Id of an interface interaction.

Add InterfaceInteraction

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.

Set Custom Type

This action sets, overwrites or removes any existing custom type and fields for an existing payment.

Set CustomField

This action sets, overwrites or removes any existing custom field for an existing payment.

Delete Payment

Endpoint: /{projectKey}/payments/{id}
Method: DELETE
OAuth2 Scopes: manage_payments:{projectKey}
Query Parameters: