Payments

Representations

Payment

• id - String
• key - String - Optional
  User-specific unique identifier for the payment (max. 256 characters).
• version - Number
• createdAt - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• 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

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, for example for example a conventional string representing Credit Card, Cash Advance etc.
• name Localized String - Optional
  A human-readable, localized name for the payment method, for example '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, defaults to Initial.

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. For example 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
OAuth 2.0 Scopes: view_payments:{projectKey}
Response Representation: Payment

Get Payment by Key

Endpoint: /{projectKey}/payments/key={key}
Method: GET
OAuth 2.0 Scopes: view_payments:{projectKey}
Response Representation: Payment

Query Payments

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

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

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
OAuth 2.0 Scopes: manage_payments:{projectKey}
Request Representation: PaymentDraft
Response Representation: Payment

Update Payment

Update Payment by ID

Endpoint: /{projectKey}/payments/{id}
Method: POST
OAuth 2.0 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
OAuth 2.0 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

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 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, for example 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, for example '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, for example one process could add a transaction of type Refund in state Initial and a PSP integration could asynchronously take care of executing the refund.

• action - String - "addTransaction"
• transaction - TransactionDraft

Change TransactionState

Changes state of a transaction. If a transaction has been executed asynchronously, it's state can be updated. For example 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.

• action - String - "addInterfaceInteraction"
• type - ResourceIdentifier to a Type
• fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional

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
OAuth 2.0 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
OAuth 2.0 Scopes: manage_payments:{projectKey}
Query Parameters:

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