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

  • id - String
  • version - Number
  • key - String - Optional
    User-specific unique identifier for the payment (max. 256 characters).
  • customer - Reference to a Customer - Optional
    A reference to the customer this payment belongs to.
  • anonymousId - String - Optional
    Identifies payments belonging to an anonymous session (the customer has not signed up/in yet).
  • interfaceId - String - Optional
    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.
  • amountPlanned - Money
    How much money this payment intends to receive from the customer. The value usually matches the cart or order gross total.
  • paymentMethodInfo - PaymentMethodInfo
  • paymentStatus - PaymentStatus
  • transactions - Array of Transaction A list of financial transactions of different TransactionTypes with different TransactionStates.
  • interfaceInteractions - Array of CustomFields
    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.
  • custom - CustomFields - Optional
  • createdAt - DateTime
  • lastModifiedAt - DateTime

PaymentDraft

  • key - String - Optional
    User-specific unique identifier for the payment (max. 256 characters).
  • customer - Reference to a Customer - Optional
    A reference to the customer this payment belongs to.
  • anonymousId - String - Optional
    Identifies payments belonging to an anonymous session (the customer has not signed up/in yet).
  • interfaceId - String - Optional
    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.
  • amountPlanned - Money
    How much money this payment intends to receive from the customer. The value usually matches the cart or order gross total.
  • paymentMethodInfo - PaymentMethodInfo - Optional
  • custom - CustomFields - Optional
  • paymentStatus - PaymentStatus - Optional
  • transactions - Array of TransactionDraft - Optional
    A list of financial transactions of different TransactionTypes with different TransactionStates.
  • interfaceInteractions - Array of CustomFieldsDraft - Optional
    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.

PaymentMethodInfo

  • paymentInterface - String - Optional
    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.
  • method - String - Optional
    The payment method that is used, e.g. e.g. a conventional string representing Credit Card, Cash Advance etc.
  • name Localized String - Optional
    A human-readable, localized name for the payment method, e.g. ‘Credit Card’.

PaymentStatus

  • interfaceCode - String - Optional
    A code describing the current status returned by the interface that processes the payment.
  • interfaceText - String - Optional
    A text describing the current status returned by the interface that processes the payment.
  • state - Reference to a State - Optional

Transaction

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.

  • id - String
    The unique ID of this object.
  • timestamp - DateTime - Optional
    The time at which the transaction took place.
  • type - TransactionType
    The type of this transaction.
  • amount - Money
  • interactionId - String - Optional
    The identifier that is used by the interface that managed the transaction (usually the PSP). If a matching interaction was logged in the interfaceInteractions array, the corresponding interaction should be findable with this ID.
  • state - TransactionState
    The state of this transaction.

TransactionDraft

  • timestamp - DateTime - Optional
    The time at which the transaction took place.
  • type - TransactionType
    The type of this transaction.
  • amount - Money
  • interactionId - String - Optional
    The identifier that is used by the interface that managed the transaction (usually the PSP). If a matching interaction was logged in the interfaceInteractions array, the corresponding interaction should be findable with this ID.
  • state - TransactionState - Optional
    The state of this transaction. If not set, currently defaults to Pending. As part of a Beta improvement initiative, we will switch the default to Initial. In the mean time, please do not depend on the default value but provide the state field explicitly.

TransactionType

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

  • 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.

TransactionState

Transactions can be in one of the following states:

  • 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.

Get Payment

Get Payment by ID

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

Get Payment by Key

Endpoint: /{projectKey}/payments/key={key}
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

  • offset - Number - Number of results skipped
  • count - Number - Number of results in this page
  • total - Number - Total number of matching results
  • results - Array of Payment

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

Update Payment by ID

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

  • version - Number - Required
    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.
  • actions - Array of UpdateAction - Required

Update Payment by Key

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

  • version - Number - Required
    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.
  • actions - Array of UpdateAction - Required

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


Set Key

  • action - String - "setKey"
  • key - String - Optional
    User-specific unique identifier for the payment (max. 256 characters). If not provided an existing key will be removed.

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.

  • action - String - "changeAmountPlanned"
  • amount - Money - The new amountPlanned

Set Customer

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

  • action - String - "setCustomer"
  • customer - Reference to a Customer
    A reference to the customer this payment belongs to.

Set AnonymousId

Sets an anonymous id that corresponds to a customer who has authenticated with an anonymous session.

  • action - String - "setAnonymousId"
  • anonymousId - String - Optional
    Anonymous Id of the anonymous customer that this payment belongs to. If this field is not set any existing anonymousId is removed.

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.

  • action - String - "setExternalId"
  • externalId - String

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.

  • action - String - "setInterfaceId"
  • interfaceId - String

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.

  • action - String - "setMethodInfoInterface"
  • interface - String

Set MethodInfoMethod

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

  • action - String - "setMethodInfoMethod"
  • method - String - Optional
    If not provided, the method is unset.

Set MethodInfoName

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

  • action - String - "setMethodInfoName"
  • name - Localized String - Optional
    If not provided, the name is unset.

Set StatusInterfaceCode

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

  • action - String - "setStatusInterfaceCode"
  • interfaceCode - String

Setting the status interface code produces the PaymentStatusInterfaceCodeSet message.

Set StatusInterfaceText

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

  • action - String - "setStatusInterfaceText"
  • interfaceText - String

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.

  • action - String - "transitionState"
  • state - Reference to a State
  • force - Boolean - Optional - Defaults to false

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.

  • action - String - "changeTransactionState"
  • transactionId - UUID of the transaction to be updated
  • state - TransactionState - The new state of this transaction.

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.

  • action - String - "changeTransactionTimestamp"
  • transactionId - UUID of the transaction to be updated
  • timestamp - DateTime - The new timestamp.

Change TransactionInteractionId

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

  • action - String - "changeTransactionInteractionId"
  • transactionId - UUID of the transaction to be updated
  • interactionId - String - The new interactionId.

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.

  • action - String - "setCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    Sets the custom fields to this value.

Set CustomField

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

Delete Payment

Delete Payment by ID

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

  • version - Number - Required
  • dataErasure - Boolean - Optional, defaults to false

Delete Payment by Key

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

  • version - Number - Required
  • dataErasure - Boolean - Optional, defaults to false