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.
The actual financial process is carried out by an external PSP, which is connected to Composable Commerce by PSP-specific integrations.
If you are using commercetools Checkout for your checkout solution, the Checkout Payments 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. MinLength:2 MaxLength: 256 Pattern: ^[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 |
amountPlanned | |
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. |
createdBy BETA | IDs and references that created the Payment. |
lastModifiedAt | Date and time (UTC) the Payment was last updated. |
lastModifiedBy BETA | IDs and references that last modified the Payment. |
PaymentDraft
key String | User-defined unique identifier for the Payment. MinLength:2 MaxLength: 256 Pattern: ^[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 |
amountPlanned | |
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 | 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 |
offset Int | Number of elements skipped. |
results Array of Payment | Payments matching the query. |
PaymentReference
id String | Unique identifier of the referenced Payment. |
typeId | "payment" References a Payment. |
obj | Contains the representation of the expanded Payment. Only present in responses to requests with Reference Expansion for Payments. |
PaymentResourceIdentifier
ResourceIdentifier of a Payment. Either id
or key
is required. If both are set, an InvalidJsonInput error is returned.
PaymentMethodInfo
paymentInterface String | Payment service that processes the Payment (for example, a PSP).
Once set, it cannot be changed.
The combination of |
method String | Payment method used, for example, credit card, or cash advance. |
name | Localizable name of the payment method. |
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 | ResourceIdentifier to a 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, |
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 |
state | State of the 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. Default:Initial |
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 Transation.
Failure
Transaction has unrecoverably failed.
Get Payment
by ID
by Key
view_payments:{projectKey}
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}/payments/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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
view_payments:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
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 | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/payments -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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
by ID
by Key
by Query Predicate
Checks if a Payment exists for a given id
. Returns a 200 OK
status if the Payment exists or a 404 Not Found
otherwise.
view_payments:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/payments/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Create Payment
Creating a Payment produces the PaymentCreated Message.
manage_payments:{projectKey}
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}/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
{"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 ID
by Key
manage_payments:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
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 PaymentUpdateAction | Update actions to be performed on the Payment. |
application/json
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
{"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
Set Key
action String | "setKey" |
key String | Value to set.
If 2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
{"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. |
{"action": "changeAmountPlanned","amount": {"currencyCode": "EUR","centAmount": 4000}}
Set Customer
action String | "setCustomer" |
customer | Value to set. If empty, any existing reference is removed. |
{"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. |
{"action": "setAnonymousId","anonymousId": "anonymousId"}
Set InterfaceId
action String | "setInterfaceId" |
interfaceId String | Value to set.
Once set, the |
{"action": "setInterfaceId","interfaceId": "InterfaceID"}
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"}}
Set StatusInterfaceCode
Produces the PaymentStatusInterfaceCodeSet Message.
action String | "setStatusInterfaceCode" |
interfaceCode String | Value to set. If empty, any existing value will be removed. |
{"action": "setStatusInterfaceCode","interfaceCode": "InterfaceCodeString"}
Set StatusInterfaceText
action String | "setStatusInterfaceText" |
interfaceText String | Value to set. If empty, any existing value will be removed. |
{"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 | ResourceIdentifier to a State. |
force Boolean | Set to false |
{"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 |
{"action": "addTransaction","transaction": {"type": "Authorization","amount": {"centAmount": 4000,"currencyCode": "EUR"}}}
Change TransactionState
Changing the TransactionState generates the PaymentTransactionStateChanged Message.
action String | "changeTransactionState" |
transactionId String | Unique identifier of the Transaction. |
state | New TransactionState. |
{"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. |
{"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. |
{"action": "changeTransactionInteractionId","transactionId": "{{transactionId}}","interactionId": "{{newInteractionId}}"}
Add InterfaceInteraction
Adding a Payment interaction generates the PaymentInteractionAdded Message.
action String | "addInterfaceInteraction" |
type | ResourceIdentifier of a Type. |
fields | Custom Fields as per FieldDefinitions of the Type. |
{"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. |
{"action": "setCustomType","type": {"id": "{{type-id}}","typeId": "type"},"fields": {"exampleStringTypeField": "TextString"}}
Set CustomField
action String | "setCustomField" |
name String | Name of the Custom Field. |
value | If |
{"action": "setCustomField","name": "ExampleStringTypeField","value": "TextString"}
Set Transaction Custom Type
action String | "setTransactionCustomType" |
transactionId String | Unique identifier of the Transaction. If the specified |
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. |
{"action": "setTransactionCustomType","type": {"id": "{{type-id}}","typeId": "type"},"fields": {"exampleStringTypeField": "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 |
{"action": "setTransactionCustomField","name": "ExampleStringTypeField","value": "TextString","transactionId": "transactionIdTest"}
Delete Payment
by ID
by Key
manage_payments:{projectKey}
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. |
dataErasure Boolean | To erase all related personal data in compliance with GDPR, set to Default: false |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/payments/{id}?version={version} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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"}