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

MyPaymentDraft

MyPaymentPagedQueryResponse

MyTransactionDraft

MyPayment

`id` String	Unique identifier of the Payment.
`version` Int	Current version of the Payment.
`customer` CustomerReference	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` CentPrecisionMoney	Money value the Payment intends to receive from the customer. The value typically matches the Cart or Order gross total.
`paymentMethodInfo` 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` PaymentMethodInfo	Information regarding the payment interface (for example, a PSP), and the specific payment method used.
`transaction` MyTransactionDraft	Financial transactions of the TransactionTypes `Authorization` or `Charge`.
`custom` CustomFieldsDraft	Custom Fields for the Payment.

MyPaymentPagedQueryResponse

PagedQueryResult with results containing an array of MyPayment.

`limit` Int	Number of results requested.
`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` DateTime	Date and time (UTC) the Transaction took place.
`type` TransactionType	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` CustomFieldsDraft	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

Expansion

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` QueryPredicate	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` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested.
`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

QueryPredicate

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

Expansion

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

Expansion

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

Set Transaction CustomField

Change AmountPlanned

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` LocalizedString	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` TransactionDraft	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` CustomFieldValue	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` CustomFieldValue	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` Money	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` Expansion	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"
    }
  ]
}