This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

My Payments

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

Custom Fields defined for the Payment.

MyPaymentDraft

amountPlanned

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

results
Array of MyPayment

MyPayments matching the query.

MyTransactionDraft

timestamp

Date and time (UTC) the Transaction took place.

type

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

amount

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 Payment

Get Payment by ID

GET
https://api.{region}.commercetools.com/{projectKey}/me/payments/{id}
OAuth 2.0 Scopes:
manage_my_payments:{projectKey}
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:
200MyPaymentasapplication/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 Payments

GET
https://api.{region}.commercetools.com/{projectKey}/me/payments
OAuth 2.0 Scopes:
manage_my_payments:{projectKey}
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.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

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
offset
Int

Number of elements skipped.

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.

Response:
200MyPaymentPagedQueryResponseasapplication/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 Payment exists

Check if Payment 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}
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 Payment 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}
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 Payment

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

Creating a Payment produces the PaymentCreated Message.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}
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:
201MyPaymentasapplication/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 Payment

Update Payment by ID

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

This endpoint can only update a Payment when it has no Transactions.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}
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:
application/json
version
Int

Expected version of the Payment on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions
Array of MyPaymentUpdateAction

Update actions to be performed on the Payment.

Response:
200MyPaymentasapplication/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": "ExampleStringTypeField",
"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": "ExampleStringTypeField",
"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

New value to set.

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

Delete Payment

Delete Payment by ID

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

This endpoint can only delete a Payment when it has no Transactions.

OAuth 2.0 Scopes:
manage_my_payments:{projectKey}
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:
200MyPaymentasapplication/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"
}
]
}