[go: up one dir, main page]

Payments

A Payment represents a series of logically connected financial transactions like reserving, charging, or refunding money.

A Payment holds information about the payment service provider (PSP), the payment method used, any related transactions, and the current state of the Payment. An Order or a Cart can reference a set of Payments using the PaymentInfo object. A Payment can also reference a Customer, or an anonymous session.
If you are using Checkout for your checkout solution, the Checkout Payment Intents API lets you request the PSP to perform actions throughout the financial process, such as payment capture, refund, and authorization cancellation.

Representations

Payment

id
String

Unique identifier of the Payment.

version
Int

Current version of the Payment.

key
String

User-defined unique identifier of the Payment.

MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
customer
Reference to a Customer associated with the Payment.
anonymousId
String
Anonymous session associated with the Payment.
interfaceId
String
Identifier used by the payment service that processes the Payment (for example, a PSP). The combination of interfaceId and the paymentInterface field on PaymentMethodInfo must be unique.
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.

paymentStatus

Current status of the Payment.

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

Represents information exchange with the payment service, for example, a PSP. An interaction may be a request sent, or a response or notification received from the payment service.

custom

Custom Fields for the Payment.

createdAt

Date and time (UTC) the Payment was initially created.

createdByBETA

IDs and references that created the Payment.

lastModifiedAt

Date and time (UTC) the Payment was last updated.

lastModifiedByBETA

IDs and references that last modified the Payment.

PaymentDraft

key
String

User-defined unique identifier for the Payment.

MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
customer
Reference to a Customer associated with the Payment.
anonymousId
String
Anonymous session associated with the Payment.
interfaceId
String
Identifier used by the payment service that processes the Payment (for example, a PSP). The combination of interfaceId and the paymentInterface field on PaymentMethodInfo must be unique. Once set, it cannot be changed.
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.

paymentStatus

Current status of the Payment.

transactions
Array of TransactionDraft
Financial transactions of the Payment. Each Transaction has a TransactionType and a TransactionState.
interfaceInteractions
Array of CustomFieldsDraft

Represents information exchange with the payment service, for example, a PSP. An interaction may be a request sent, or a response or notification received from the payment service.

custom

Custom Fields for the Payment.

PaymentPagedQueryResponse

PagedQueryResult with results containing an array of Payment.
limit
Int
Default20Minimum0Maximum500
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.
Default0Maximum10000
results
Array of Payment
Payments matching the query.

PaymentReference

id
String
Unique identifier of the referenced Payment.
typeId
payment

Type of referenced resource.

obj
Contains the representation of the expanded Payment. Only present in responses to requests with Reference Expansion for Payments.

PaymentKeyReference

Used by the Import API to identify a Payment.
key
String

User-defined unique identifier of the referenced Payment.

typeId
payment

Type of referenced resource.

PaymentResourceIdentifier

ResourceIdentifier of a Payment. Either id or key is required. If both are set, an InvalidJsonInput error is returned.
id
String
Unique identifier of the referenced Payment. Required if key is absent.
key
String
User-defined unique identifier of the referenced Payment. Required if id is absent.
typeId
payment
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

PaymentMethodInfo

Represents a snapshot of the PaymentMethod data used for a Payment.

paymentInterface
String
Payment service that processes the Payment—for example, a PSP. The combination of paymentInterface and the interfaceId of a Payment is unique.
method
String

Payment method used—for example, a credit card or direct debit.

name

Name of the Payment Method.

tokenBETA

Tokenized representation of the Payment Method used by the payment interface.

interfaceAccountBETA
String

Account or instance of the payment interface when multiple accounts are used (per interface).

customBETA

Custom Fields of the PaymentMethodInfo.

PaymentMethodInfoDraft BETA

paymentInterface
String
Payment service that processes the Payment—for example, a PSP. The combination of paymentInterface and the interfaceId of a Payment must be unique.

The value cannot be modified after it is set.

method
String

Payment method to use—for example, a credit card or direct debit.

name

Name of the Payment Method.

token

Tokenized representation of the Payment Method used by the payment interface.

interfaceAccount
String

Account or instance of the payment interface when multiple accounts are used (per interface).

custom

Custom fields for the PaymentMethodInfo.

PaymentStatus

interfaceCode
String

External reference that identifies the current status of the Payment.

interfaceText
String

Text describing the current status of the Payment.

state

PaymentStatusDraft

interfaceCode
String

External reference that identifies the current status of the Payment.

interfaceText
String

Text describing the current status of the Payment.

state

Transaction

Represents a financial transaction typically created as a result of a notification from the payment service.

id
String

Unique identifier of the Transaction.

timestamp

Date and time (UTC) the Transaction took place.

type
Type of the Transaction. For example, Authorization.
amount

Money value of the Transaction.

interactionId
String
Identifier used by the interface that manages the Transaction (usually the PSP). If a matching interaction was logged in the interfaceInteractions array, the corresponding interaction can be found with this ID.
state

State of the Transaction.

interfaceId
String

Identifier used by the payment service that processes the Payment (for example, a PSP) in the current transaction.

custom

Custom Fields defined for the Transaction.

TransactionDraft

timestamp

Date and time (UTC) the Transaction took place.

type

Type of the Transaction.

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.

state

State of the Transaction.

DefaultInitial
interfaceId
String

Identifier used by the payment service that processes the Payment (for example, a PSP) in the current transaction.

custom

Custom Fields of the Transaction.

TransactionType

Authorization

Financially reliable reservation of an amount. Typically does not indicate an actual transfer of money.

CancelAuthorization

Explicit cancellation of an authorized amount before its expiry.

Charge

Collection of money from the customer. Can use an authorized amount or be directly executed.

Refund

Explicit transfer of money back to the customer.

Chargeback

Customer-initiated transfer of money back to the customer.

TransactionState

Transactions can be in one of the following States:

Initial

Initial State. The payment service has not accepted the Transaction yet.

Pending

The payment service has accepted the Transaction, but it is not completed yet.

Success

The payment service has confirmed the successful completion of the Transaction.

Failure

Transaction has unrecoverably failed.

Get Payment

Get Payment by ID

GET
https://api.{region}.commercetools.com/{projectKey}/payments/{id}
Retrieves a Payment with the provided id.
OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
id
String
id of the Payment.
Query parameters:
expand
The parameter can be passed multiple times.
Response:
200

Payment

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {

  },
  "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"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Get Payment by Key

GET
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}
Retrieves a Payment with the provided key.
OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
key
String
key of the Payment.
Query parameters:
expand
The parameter can be passed multiple times.
Response:
200

Payment

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {

  },
  "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"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Query Payments

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

Retrieves Payments in the Project.

OAuth 2.0 Scopes:
view_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.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
Default: 20
Minimum: 0
Maximum: 500
offset
Int
Number of elements skipped.
Default: 0
Maximum: 10000
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
The parameter can be passed multiple times.
Response:
200

PaymentPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: PaymentPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "459e32dc-74ef-4189-bbd0-932275bb027c",
      "version": 1,
      "key": "123456",
      "interfaceId": "78901",
      "amountPlanned": {
        "type": "centPrecision",
        "fractionDigits": 2,
        "currencyCode": "USD",
        "centAmount": 1000
      },
      "paymentMethodInfo": {
        "paymentInterface": "STRIPE",
        "method": "CREDIT_CARD",
        "name": {
          "en": "Credit Card"
        }
      },
      "paymentStatus": {

      },
      "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"
        }
      ],
      "interfaceInteractions": [],
      "createdAt": "2015-10-20T08:51:43.082Z",
      "lastModifiedAt": "2015-10-20T08:51:43.082Z"
    }
  ]
}

Check if Payment exists

Check if Payment exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/payments/{id}
Checks if a Payment exists with the provided id. Returns a 200 status if the Payment exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
id
String
id of the Payment.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if Payment exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}
Checks if a Payment exists with the provided key. Returns a 200 status if the Payment exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
key
String
key of the Payment.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if Payment exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/payments
Checks if one or more Payments exist for the provided query predicate. Returns a 200 status if any Payments match the query predicate, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_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}/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Create Payment

POST
https://api.{region}.commercetools.com/{projectKey}/payments
Creates a Payment in the Project. Creating a Payment produces the PaymentCreated Message.
OAuth 2.0 Scopes:
manage_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:PaymentDraftasapplication/json
Response:
201

Payment

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "123456",
  "interfaceId" : "789011",
  "amountPlanned" : {
    "currencyCode" : "USD",
    "centAmount" : 1000
  },
  "paymentMethodInfo" : {
    "paymentInterface" : "STRIPE",
    "method" : "CREDIT_CARD",
    "name" : {
      "en" : "Credit Card"
    }
  },
  "transactions" : [ {
    "timestamp" : "2015-10-20T08:54:24.000Z",
    "type" : "Charge",
    "amount" : {
      "currencyCode" : "USD",
      "centAmount" : 1000
    },
    "state" : "Pending"
  } ]
}
DATA
201 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {

  },
  "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"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Update Payment

Update Payment by ID

POST
https://api.{region}.commercetools.com/{projectKey}/payments/{id}
Updates a Payment in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
id
String
id of the Payment.
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

Update actions to be performed on the Payment.

Response:
200

Payment

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "transitionState",
    "state" : {
      "typeId" : "state",
      "id" : "18748fe6-7f77-456a-96c8-913b1e4bbc9c"
    }
  } ]
}
DATA
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {

  },
  "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"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Update Payment by Key

POST
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}
Updates a Payment in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
key
String
key of the Payment.
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

Update actions to be performed on the Payment.

Response:
200

Payment

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "transitionState",
    "state" : {
      "typeId" : "state",
      "id" : "18748fe6-7f77-456a-96c8-913b1e4bbc9c"
    }
  } ]
}
DATA
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {

  },
  "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"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Update actions

On Payment

Set Key

action
String
"setKey"
key
String
Value to set. If key is absent or null, the existing key, if any, will be removed.
MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
Example: json
{
  "action": "setKey",
  "key": "String"
}

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

Set Customer

action
String
"setCustomer"
customer

Value to set. If empty, any existing reference is removed.

Example: json
{
  "action": "setCustomer",
  "customer": {
    "typeId": "customer",
    "id": "{{customer-id}}"
  }
}

Set AnonymousId

If the Payment is already associated with a Customer, an InvalidOperation error is returned.
action
String
"setAnonymousId"
anonymousId
String

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

Example: json
{
  "action": "setAnonymousId",
  "anonymousId": "anonymousId"
}

Set InterfaceId

This action generates the PaymentInterfaceIdSet Message.
action
String
"setInterfaceId"
interfaceId
String
Value to set. The combination of interfaceId and paymentInterface of a PaymentMethodInfo must be unique.

The value cannot be modified after it is set.

Example: json
{
  "action": "setInterfaceId",
  "interfaceId": "InterfaceID"
}

Set MethodInfo BETA

This action lets you update multiple fields of a PaymentMethodInfo in one operation. Only fields with explicitly provided values will be updated.

action
String
"setMethodInfo"
paymentInterface
String
Payment service that processes the Payment—for example, a PSP. The combination of paymentInterface and the interfaceId of a Payment must be unique. The value cannot be modified after it is set.
Setting this field is equivalent to the setMethodInfoInterface action and will generate the PaymentMethodInfoInterfaceSet Message.
method
String

Payment method to use—for example, a credit card or direct debit. If empty, any existing value will be removed.

Setting this field is equivalent to the setMethodInfoMethod action and will generate the PaymentMethodInfoMethodSet Message.
name

Name of the Payment Method. If empty, any existing value will be removed.

Setting this field is equivalent to the setMethodInfoName action and will generate the PaymentMethodInfoNameSet Message.
token

Tokenized payment method information of the Payment Method. If empty, any existing value will be removed.

Setting this field is equivalent to the setMethodInfoToken action and will generate the PaymentMethodInfoTokenSet Message.
interfaceAccount
String

Account or instance of the payment interface when multiple accounts are used (per interface). If empty, any existing value will be removed.

Setting this field is equivalent to the setMethodInfoInterfaceAccount action and will generate the PaymentMethodInfoInterfaceAccountSet Message.
custom

Custom Fields for the PaymentMethodInfo. If not provided, any existing Custom Fields will be removed, including the Custom Type.

Setting this field is equivalent to the setMethodInfoCustomType and setMethodInfoCustomField actions, and will generate the following Messages:
Example: json
{
  "action": "setMethodInfo",
  "paymentInterface": "STRIPE",
  "method": "CREDITCARD",
  "name": {
    "en": "Credit Card",
    "de": "Kreditkarte"
  },
  "token": {
    "value": "sk_test_123456789"
  },
  "interfaceAccount": "acct_1234567890",
  "custom": {
    "type": {
      "id": "{{type-id}}",
      "typeId": "type"
    },
    "fields": {
      "last4": 1234,
      "brand": "VISA"
    }
  }
}

Set MethodInfo Interface

This action generates the PaymentMethodInfoInterfaceSet Message.
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 MethodInfo Method

This action generates the PaymentMethodInfoMethodSet Message.
action
String
"setMethodInfoMethod"
method
String

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

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

Set MethodInfo Name

This action generates the PaymentMethodInfoNameSet Message.
action
String
"setMethodInfoName"
name

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

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

Set MethodInfo Token BETA

This action generates the PaymentMethodInfoTokenSet Message.
action
String
"setMethodInfoToken"
token

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

Example: json
{
  "action": "setMethodInfoToken",
  "token": {
    "value": "1234-5678-9010-1234"
  }
}

Set MethodInfo InterfaceAccount BETA

This action generates the PaymentMethodInfoInterfaceAccountSet Message.
action
String
"setMethodInfoInterfaceAccount"
interfaceAccount
String

New account or instance of the payment interface. If empty, any existing value will be removed.

Example: json
{
  "action": "setMethodInfoInterfaceAccount",
  "interfaceAccount": "ADYEN-123"
}

Set MethodInfo Custom Type BETA

Adding or updating a Custom Type on a PaymentMethodInfo generates the PaymentMethodInfoCustomTypeSet Message, removing one generates the PaymentMethodInfoCustomTypeRemoved Message.
action
String
"setMethodInfoCustomType"
type
Defines the Type that extends the paymentMethodInfo with Custom Fields.
fields
Sets the Custom Fields fields for the paymentMethodInfo.
Example: json
{
  "action": "setMethodInfoCustomType",
  "type": {
    "key": "payment-method-info-cc-last4",
    "typeId": "type"
  },
  "fields": {
    "last4": 1234
  }
}

Set MethodInfo CustomField BETA

Adding a Custom Field to a PaymentMethodInfo generates the PaymentMethodInfoCustomFieldAdded Message, removing one generates the PaymentMethodInfoCustomFieldRemoved Message, and updating an existing one generates the PaymentMethodInfoCustomFieldChanged Message.
action
String
"setMethodInfoCustomField"
name
String
Name of the Custom Field.
value
If value is absent or null, this field will be removed if it exists. If value is provided, it is set for the field defined by name. Trying to remove a field that does not exist will fail with an InvalidOperation error.
Example: json
{
  "action": "setMethodInfoCustomField",
  "name": "last4",
  "value": 4567
}

Set StatusInterfaceCode

Produces the PaymentStatusInterfaceCodeSet Message.
action
String
"setStatusInterfaceCode"
interfaceCode
String

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

Example: json
{
  "action": "setStatusInterfaceCode",
  "interfaceCode": "InterfaceCodeString"
}

Set StatusInterfaceText

action
String
"setStatusInterfaceText"
interfaceText
String

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

Example: json
{
  "action": "setStatusInterfaceText",
  "interfaceText": "InterfaceTextString"
}

Transition State

If the Payment has no current State, initial must be true for the new State. If the existing State has transitions set, the new State must be a valid transition. If the existing State has no transitions set, no validations are performed when transitioning to the new State.
Transitioning the State of a Payment produces the PaymentStatusStateTransition Message.
action
String
"transitionState"
state
force
Boolean
Set to true to skip validations when transitioning to the new State.
Defaultfalse
Example: json
{
  "action": "transitionState",
  "state": {
    "typeId": "state",
    "id": "{{paymentStateId}}"
  }
}

Add Transaction

Adding a Transaction to a Payment generates the PaymentTransactionAdded Message.
action
String
"addTransaction"
transaction
Value to append to the transactions array.
Example: json
{
  "action": "addTransaction",
  "transaction": {
    "type": "Authorization",
    "amount": {
      "centAmount": 4000,
      "currencyCode": "EUR"
    }
  }
}

Add InterfaceInteraction

Adding a Payment interaction generates the PaymentInteractionAdded Message.
action
String
"addInterfaceInteraction"
type
fields
Example: json
{
  "action": "addInterfaceInteraction",
  "type": {
    "typeId": "type",
    "id": "{{type-id}}"
  }
}

Set Custom Type

action
String
"setCustomType"
type
Defines the Type that extends the Payment with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Payment.
fields
Sets the Custom Fields fields for the Payment.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

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"
}

On Transaction

Change TransactionState

Changing the TransactionState generates the PaymentTransactionStateChanged Message.
action
String
"changeTransactionState"
transactionId
String
Unique identifier of the Transaction.
state

New TransactionState.

Example: json
{
  "action": "changeTransactionState",
  "transactionId": "{{transactionId}}",
  "state": "Failure"
}

Change TransactionTimestamp

action
String
"changeTransactionTimestamp"
transactionId
String
Unique identifier of the Transaction.
timestamp

Timestamp of the Transaction as reported by the payment service.

Example: json
{
  "action": "changeTransactionTimestamp",
  "transactionId": "{{transactionId}}",
  "timestamp": "2018-10-12T14:00:00.000Z"
}

Change TransactionInteractionId

action
String
"changeTransactionInteractionId"
transactionId
String
Unique identifier of the Transaction.
interactionId
String

New value to set.

Example: json
{
  "action": "changeTransactionInteractionId",
  "transactionId": "{{transactionId}}",
  "interactionId": "{{newInteractionId}}"
}

Set TransactionInterfaceId

Setting the transaction interface ID produces the PaymentTransactionInterfaceIdSet Message.
action
String
"setTransactionInterfaceId"
transactionId
String
Unique identifier of the Transaction.
interfaceId
String
Identifier used by the payment service that processes the Payment (for example, a PSP) in the current transaction. It must be unique across all transactions. If interfaceId is absent, this field will be removed from the specified Transaction, if it exists.
Example: json
{
  "action": "setTransactionInterfaceId",
  "transactionId": "{{transactionId}}",
  "interfaceId": "{{interfaceId}}"
}

Set Transaction Custom Type

action
String
"setTransactionCustomType"
transactionId
String
Unique identifier of the Transaction. If the specified transactionId does not exist, the request will fail with an InvalidOperation error.
type
Defines the Type that extends the Transaction with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Transaction.
fields
Sets the Custom Fields fields for the Transaction.
Example: json
{
  "action": "setTransactionCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  },
  "transactionId": "transactionIdTest"
}

Set Transaction CustomField

action
String
"setTransactionCustomField"
transactionId
String
Unique identifier of the Transaction.
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",
  "transactionId": "transactionIdTest"
}

Delete Payment

Delete Payment by ID

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

Deletes a Payment in the Project.

OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
id
String
id of the Payment.
Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean
To erase all related personal data in compliance with GDPR, set to true.
Default: false
Response:
200

Payment

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/payments/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {

  },
  "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"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}

Delete Payment by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/payments/key={key}

Deletes a Payment in the Project.

OAuth 2.0 Scopes:
manage_payments:{projectKey}
Path parameters:
region
String
Region in which the Project is hosted.
projectKey
String
key of the Project.
key
String
key of the Payment.
Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean
To erase all related personal data in compliance with GDPR, set to true.
Default: false
Response:
200

Payment

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/payments/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Paymentjson
{
  "id": "776f9240-09e1-4416-a34f-32fa80f0333f",
  "version": 1,
  "key": "123456",
  "interfaceId": "789011",
  "amountPlanned": {
    "type": "centPrecision",
    "fractionDigits": 2,
    "currencyCode": "USD",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "STRIPE",
    "method": "CREDIT_CARD",
    "name": {
      "en": "Credit Card"
    }
  },
  "paymentStatus": {

  },
  "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"
    }
  ],
  "interfaceInteractions": [],
  "createdAt": "2015-10-20T08:54:11.480Z",
  "lastModifiedAt": "2015-10-20T08:54:11.480Z"
}