My Payments

Elevate, May 20-22-2025, Miami Beach, Florida

My Payments represents Payments associated with a specific Customer.

The My Payments endpoints require an access token from the password flow or anonymous session flow. The endpoints intentionally provide access to a limited subset of the fields on a Payment. This provides extra security in scenarios when the client application must communicate directly with the Composable Commerce API on behalf of a customer.

The My Payments API can help in synchronous or asynchronous communication with a payment service provider (PSP). For example, if a client application receives a token for a credit card from a payment service, it can create a MyPaymentDraft with the token, and optionally add a Transaction to authorize a certain amount. The Payment can then be passed to another service that uses the general Payment endpoint and can communicate with the PSP to charge the credit cart. This service can be triggered by a Subscription, or be implemented as an API Extension.

After a Transaction is added to a Payment, it can no longer be updated or deleted using My Payments.

Representations

MyPayment

id​
String​

Unique identifier of the Payment.

version​
Int​

Current version of the Payment.

customer​

Reference to a Customer associated with the Payment. Set automatically with a password flow token. Either customer or anonymousId is present.

anonymousId​
String​

Anonymous session associated with the Payment. Set automatically with a token for an anonymous session. Either customer or anonymousId is present.

amountPlanned​

Money value the Payment intends to receive from the customer. The value typically matches the Cart or Order gross total.

paymentMethodInfo​

Information regarding the payment interface (for example, a PSP), and the specific payment method used.

transactions​
Array of Transaction​

Financial transactions of the Payment. Each Transaction has a TransactionType and a TransactionState.

custom​
CustomFields​

Custom Fields defined for the Payment.

MyPaymentDraft

amountPlanned​
Money​

Money value the Payment intends to receive from the customer. The value usually matches the Cart or Order gross total.

paymentMethodInfo​

Information regarding the payment interface (for example, a PSP), and the specific payment method used.

transaction​

Financial transactions of the TransactionTypes Authorization or Charge.

custom​

Custom Fields for the Payment.

MyPaymentPagedQueryResponse

PagedQueryResult with results containing an array of MyPayment.

limit​
Int​

Number of results requested.

Default: 20​Minimum: 0​Maximum: 500​
count​
Int​

Actual number of results returned.

total​
Int​

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

offset​
Int​

Number of elements skipped.

Default: 0​Maximum: 10000​
results​
Array of MyPayment​

MyPayments matching the query.

MyTransactionDraft

timestamp​
DateTime​

Date and time (UTC) the Transaction took place.

type​

Type of the Transaction. Only Authorization or Charge is allowed.

amount​
Money​

Money value for the Transaction.

interactionId​
String​

Identifier used by the payment service that manages the Transaction. Can be used to correlate the Transaction to an interface interaction.

custom​

Custom Fields of the Transaction.

Get MyPayment

GET
https://api.{region}.commercetools.com/{projectKey}/me/payments/{id}

Returns a Payment for a given id.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the MyPayment.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

MyPayment

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/me/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: MyPaymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "customer": {
    "typeId": "customer",
    "id": "2c0b6ab8-5eea-4e19-b815-d150c47da5db"
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ]
}

Query MyPayments

GET
https://api.{region}.commercetools.com/{projectKey}/me/payments

Returns all Payments that match a given Query Predicate.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​​
The parameter can be passed multiple times.
sort
​​
The parameter can be passed multiple times.
expand
​​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

Default: 0​
withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Default: true​
var.<varName>
​
String
​

Predicate parameter values.

The parameter can be passed multiple times.
Response:
200

MyPaymentPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/me/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: MyPaymentPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "459e32dc-74ef-4189-bbd0-932275bb027c",
      "version": 1,
      "amountPlanned": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "customer": {
        "typeId": "customer",
        "id": "2c0b6ab8-5eea-4e19-b815-d150c47da5db"
      },
      "paymentMethodInfo": {
        "paymentInterface": "STRIPE",
        "method": "CREDIT_CARD",
        "name": {
          "en": "Credit Card"
        }
      },
      "transactions": [
        {
          "id": "2e318aa5-8af4-4db1-909d-e7142f7d174f",
          "timestamp": "2015-10-20T08:51:56.000Z",
          "type": "Charge",
          "amount": {
            "type": "centPrecision",
            "fractionDigits": 2,
            "currencyCode": "USD",
            "centAmount": 1000
          },
          "state": "Pending"
        }
      ]
    }
  ]
}

Check if MyPayment exists

Check if MyPayment exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/payments/{id}

Checks if a Payment exists for a given id. Returns a 200 OK status if the Payment exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the MyPayment.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if MyPayment exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/payments

Checks if a Payment exists for a given Query Predicate. Returns a 200 OK status if any Payments match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Create MyPayment

POST
https://api.{region}.commercetools.com/{projectKey}/me/payments

Creates a Payment for the Customer or an anonymous user. Creating a Payment produces the PaymentCreated Message.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:MyPaymentDraftasapplication/json
Response:
201

MyPayment

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/me/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "amountPlanned" : {
    "currencyCode" : "USD",
    "centAmount" : 1000
  },
  "paymentMethodInfo" : {
    "paymentInterface" : "STRIPE",
    "method" : "CREDIT_CARD",
    "name" : {
      "en" : "Credit Card"
    }
  },
  "transaction" : {
    "timestamp" : "2015-10-20T08:54:24.000Z",
    "type" : "Charge",
    "amount" : {
      "currencyCode" : "USD",
      "centAmount" : 1000
    }
  }
}
DATA
201 Response Example: MyPaymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "customer": {
    "typeId": "customer",
    "id": "2c0b6ab8-5eea-4e19-b815-d150c47da5db"
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ]
}

Update MyPayment

POST
https://api.{region}.commercetools.com/{projectKey}/me/payments/{id}

Updates a Payment for a given id. You can only update a Payment if it has no Transactions.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the MyPayment.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:MyPaymentUpdateasapplication/json
Response:
200

MyPayment

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/me/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeAmountPlanned",
    "amount" : {
      "currencyCode" : "USD",
      "centAmount" : 1000
    }
  } ]
}
DATA
200 Response Example: MyPaymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "customer": {
    "typeId": "customer",
    "id": "2c0b6ab8-5eea-4e19-b815-d150c47da5db"
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ]
}

Update actions

Set MethodInfoInterface

action​
String​
"setMethodInfoInterface"
interface​
String​

Value to set. Once set, the paymentInterface of the paymentMethodInfo cannot be changed.

Example: json
{
  "action": "setMethodInfoInterface",
  "interface": "MethodInfoInterfaceString"
}

Set MethodInfoMethod

action​
String​
"setMethodInfoMethod"
method​
String​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setMethodInfoMethod",
  "method": "MethodInfoMethodString"
}

Set MethodInfoName

action​
String​
"setMethodInfoName"
name​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action": "setMethodInfoName",
  "name": {
    "de": "MethodInfoNameStringDE",
    "en": "MethodInfoNameStringEN"
  }
}

Add Transaction

Adding a Transaction to a Payment generates the PaymentTransactionAdded Message. Once a Transaction is added to the Payment, it can no longer be updated or deleted using the My Payments API.

action​
String​
"addTransaction"
transaction​

Transaction to add to the Payment.

Example: json
{
  "action": "addTransaction",
  "transaction": {
    "type": "Authorization",
    "amount": {
      "centAmount": 4000,
      "currencyCode": "EUR"
    }
  }
}

Set CustomField

action​
String​
"setCustomField"
name​
String​

Name of the Custom Field.

value​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action": "setCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Set Transaction CustomField

action​
String​
"setTransactionCustomField"
name​
String​

Name of the Custom Field.

value​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action": "setTransactionCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Change AmountPlanned

Can be used to update the Payment if a customer changes the Cart, or adds or removes a CartDiscount during checkout.

action​
String​
"changeAmountPlanned"
amount​
Money​

New value to set.

Example: json
{
  "action": "changeAmountPlanned",
  "amount": {
    "currencyCode": "EUR",
    "centAmount": 4000
  }
}

Delete MyPayment

DELETE
https://api.{region}.commercetools.com/{projectKey}/me/payments/{id}

Deletes the Payment for a given id. You can only delete a Payment if it has no Transactions.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}customer_id:{id}anonymous_id:{id}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the MyPayment.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​​
The parameter can be passed multiple times.
Response:
200

MyPayment

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/me/payments/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: MyPaymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "customer": {
    "typeId": "customer",
    "id": "2c0b6ab8-5eea-4e19-b815-d150c47da5db"
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "transactions": [
    {
      "id": "14748fe6-7f77-456a-96c8-913b1e4bbc9a",
      "timestamp": "2015-10-20T08:54:24.000Z",
      "type": "Charge",
      "amount": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "state": "Pending"
    }
  ]
}