Documentation
BETA

My Payments

The My Payments endpoint creates and provides access to payments scoped to a specific user. The endpoint requires an access token from the password flow or anonymous session flow.

The My Payments endpoint intentionally provides access to a limited subset of the fields (a payment stub) on a Payment. This provides extra security in scenarios when the client application must communicate directly with the commercetools API on behalf of a customer. For example, if a client application receives a token for a credit card from a payment service provider, it can create a payment stub with the token, and optionally add a transaction to authorize a certain amount. The payment stub can be passed to another service using the full Payment endpoint that communicates with the payment service provider to authorize and later charge the credit cart. This service can be triggered by a Subscription, or be implemented as an API Extension.

The My Payments endpoint allows the client application to view the payment's current state, but the payment cannot be updated or deleted after adding the first transaction.

Representations

MyPayment

This is the representation of the Payment that is returned from all of the following endpoints. It represents the limited part of the Payment that can be manipulated through these endpoints.

  • id - String
  • version - Number
  • 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).
  • amountPlanned - CentPrecisionMoney
    How much money this payment intends to receive from the customer. The value usually matches the cart or order gross total.
  • paymentMethodInfo - PaymentMethodInfo
  • transactions - Array of Transaction A list of financial transactions of different TransactionTypes with different TransactionStates.
  • custom - CustomFields - Optional

MyPaymentDraft

A MyPaymentDraft is the object submitted as payload to the Create MyPayment method. The customer field of MyPayment is automatically set with a password flow token. The anonymousId is automatically set with a token for an anonymous session.

  • 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
  • transaction - MyTransactionDraft - Optional
    A list of financial transactions of the Authorization or ChargeTransactionTypes.

MyTransactionDraft

  • timestamp - DateTime - Optional
    The time at which the transaction took place.
  • type - TransactionType
    The type of this transaction. Only the Authorization or ChargeTransactionTypes are allowed here.
  • amount - Money
  • interactionId - String - Optional
    The identifier that is used by the interface that managed the transaction. This is usually the Payment Service Provider (PSP). If a matching interaction was logged in the interfaceInteractions array, the corresponding interaction should be findable with this ID.
  • custom - CustomFields - Optional

The state is set to the Initial TransactionState.

Get MyPayment by ID

Endpoint: /{projectKey}/me/payments/{id}
Method: GET
OAuth 2.0 Scopes: manage_my_payments:{projectKey}
Response Representation: MyPayment

Query MyPayments

Endpoint: /{projectKey}/me/payments
Method: GET
OAuth 2.0 Scopes: manage_my_payments:{projectKey}
Response Representation: PagedQueryResult with the results array of MyPayment

Query Parameters:

Create MyPayment

Endpoint: /{projectKey}/me/payments
Method: POST
OAuth 2.0 Scopes: manage_my_payments:{projectKey}
Request Representation: MyPaymentDraft
Response Representation: MyPayment

Update MyPayment

Endpoint: /{projectKey}/me/payments/{id}
Method: POST
OAuth 2.0 Scopes: manage_my_payments:{projectKey}
Response Representation: MyPayment
Fields:

  • version - Number - Required
    The expected version of the payment 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
    The list of update actions to be performed on the payment.

Update actions

Set MethodInfoInterface

As described here.

Set MethodInfoMethod

As described here.

Set MethodInfoName

As described here.

Add Transaction

Adds a new financial transaction. It can be used for asynchronous communication, for example one process could add a transaction of type Charge in state Initial and a PSP integration could asynchronously take care of executing the charge.

Set CustomField

As described here.

Set Transaction CustomField

As described here.

Change AmountPlanned

As described here.

Delete MyPayment

Removes a MyPayment.

Endpoint: /{projectKey}/me/payments/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_my_payments:{projectKey}
Response Representation: MyPayment
Query parameters:

  • version - Number - Required