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 |
anonymousId ​String​ | Anonymous session associated with the Payment. Set automatically with a token for an anonymous session. Either |
amountPlanned ​ | |
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​ | |
paymentMethodInfo ​ | Information regarding the payment interface (for example, a PSP), and the specific payment method used. |
transaction ​ | Financial transactions of the TransactionTypes |
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 |
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 |
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
Returns a Payment for a given id
.
manage_my_payments:{projectKey}
customer_id:{id}
anonymous_id:{id}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/me/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
Returns all Payments that match a given Query Predicate.
manage_my_payments:{projectKey}
customer_id:{id}
anonymous_id:{id}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
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 Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/me/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
Checks if a Payment exists for a given id
. Returns a 200 OK
status if the Payment exists or a 404 Not Found
otherwise.
manage_my_payments:{projectKey}
customer_id:{id}
anonymous_id:{id}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/me/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if MyPayment exists by Query Predicate
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.
manage_my_payments:{projectKey}
customer_id:{id}
anonymous_id:{id}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/me/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create MyPayment
Creates a Payment for the Customer or an anonymous user. Creating a Payment produces the PaymentCreated Message.
manage_my_payments:{projectKey}
customer_id:{id}
anonymous_id:{id}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
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
{
"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
Updates a Payment for a given id
.
You can only update a Payment if it has no Transactions.
manage_my_payments:{projectKey}
customer_id:{id}
anonymous_id:{id}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
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
{
"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 |
{
"action": "setMethodInfoInterface",
"interface": "MethodInfoInterfaceString"
}
Set MethodInfoMethod
action ​String​ | "setMethodInfoMethod" |
method ​String​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setMethodInfoMethod",
"method": "MethodInfoMethodString"
}
Set MethodInfoName
action ​String​ | "setMethodInfoName" |
name ​ | Value to set. If empty, any existing value will be removed. |
{
"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. |
{
"action": "addTransaction",
"transaction": {
"type": "Authorization",
"amount": {
"centAmount": 4000,
"currencyCode": "EUR"
}
}
}
Set CustomField
action ​String​ | "setCustomField" |
name ​String​ | Name of the Custom Field. |
value ​ | If |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}
Set Transaction CustomField
action ​String​ | "setTransactionCustomField" |
name ​String​ | Name of the Custom Field. |
value ​ | If |
{
"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. |
{
"action": "changeAmountPlanned",
"amount": {
"currencyCode": "EUR",
"centAmount": 4000
}
}
Delete MyPayment
Deletes the Payment for a given id
.
You can only delete a Payment if it has no Transactions.
manage_my_payments:{projectKey}
customer_id:{id}
anonymous_id:{id}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/me/payments/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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"
}
]
}