commercetools Payments API

openapi: 3.2.0
info:
  title: commercetools HTTP Payments API
  description: The commercetools HTTP API is the core REST interface for programmatic access to all data and functionality within a Composable Commerce project. It covers a broad range of commerce resources including products, product types, categories, carts, orders, customers, payments, discounts, inventory, shipping methods, stores, and business units. All resources follow RESTful conventions using standard HTTP verbs and return JSON responses. Authentication is handled via OAuth 2.0 client credentials, and requests are scoped per project and resource type.
  version: '1.0'
  contact:
    name: commercetools Support
    url: https://support.commercetools.com
  termsOfService: https://commercetools.com/terms-conditions
servers:
- url: https://api.{region}.commercetools.com
  description: Production Server
  variables:
    region:
      default: us-central1.gcp
      enum:
      - us-central1.gcp
      - us-east-2.aws
      - europe-west1.gcp
      - eu-central-1.aws
      - australia-southeast1.gcp
      description: The deployment region for the commercetools API.
security:
- bearerAuth: []
tags:
- name: Payments
  description: Track payment transactions and PSP interactions associated with orders.
paths:
  /{projectKey}/payments:
    get:
      operationId: listPayments
      summary: List payments
      description: Returns a paginated list of payments in the project. Supports filtering by customer, interface ID, and other predicates. Payments track financial transactions and PSP interactions associated with orders.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: A paged list of payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPagedQueryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPayment
      summary: Create a payment
      description: Creates a new payment resource representing intent to pay a specific amount. The payment records PSP details, method information, and transaction history. Payments are linked to orders via the cart or order update actions.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/projectKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentDraft'
      responses:
        '201':
          description: The created payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
  /{projectKey}/payments/{id}:
    get:
      operationId: getPaymentById
      summary: Get a payment by ID
      description: Retrieves a single payment by its system-generated ID, including all transactions, interface interactions, payment method info, and current status.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The requested payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updatePaymentById
      summary: Update a payment by ID
      description: Applies update actions to the payment with the given ID. Supported actions include adding transactions, setting the payment status, adding interface interactions, and setting custom fields.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentUpdate'
      responses:
        '200':
          description: The updated payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
components:
  schemas:
    PaymentStatus:
      type: object
      description: The current status of a payment including PSP-specific state information.
      properties:
        interfaceCode:
          type: string
          description: PSP-specific status code.
        interfaceText:
          type: string
          description: PSP-specific status message.
        state:
          $ref: '#/components/schemas/Reference'
    Reference:
      type: object
      description: A reference to another resource by its typeId and id.
      required:
      - typeId
      - id
      properties:
        typeId:
          type: string
          description: The type identifier of the referenced resource (e.g., 'product', 'category').
        id:
          type: string
          description: The system-generated unique identifier of the referenced resource.
    Transaction:
      type: object
      description: A single financial transaction within a payment (authorization, charge, refund, etc.).
      required:
      - id
      - type
      - amount
      - state
      properties:
        id:
          type: string
          description: System-generated unique identifier for the transaction.
        timestamp:
          type: string
          format: date-time
          description: When the transaction was processed.
        type:
          type: string
          enum:
          - Authorization
          - CancelAuthorization
          - Charge
          - Refund
          - Chargeback
          description: The type of financial transaction.
        amount:
          $ref: '#/components/schemas/Money'
        interactionId:
          type: string
          description: PSP-provided identifier for this transaction.
        state:
          type: string
          enum:
          - Initial
          - Pending
          - Success
          - Failure
          description: Current processing state of the transaction.
    PaymentUpdate:
      type: object
      description: Request body for updating a payment.
      required:
      - version
      - actions
      properties:
        version:
          type: integer
          description: Current version for optimistic concurrency control.
        actions:
          type: array
          items:
            type: object
          description: List of update actions to apply to the payment.
    LocalizedString:
      type: object
      description: A map of locale keys to string values used for multilingual content. Keys follow IETF language tag format (e.g., 'en', 'de', 'en-US').
      additionalProperties:
        type: string
    Money:
      type: object
      description: A monetary value with currency code and amount in the smallest currency unit.
      required:
      - currencyCode
      - centAmount
      properties:
        currencyCode:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 three-letter currency code (e.g., USD, EUR).
        centAmount:
          type: integer
          description: The amount in the smallest indivisible unit of the currency.
        fractionDigits:
          type: integer
          description: Number of fraction digits for the currency. Defaults to 2.
    Payment:
      type: object
      description: A payment resource tracking financial transactions and PSP interactions for an order.
      required:
      - id
      - version
      - amountPlanned
      - paymentMethodInfo
      - transactions
      properties:
        id:
          type: string
          description: System-generated unique identifier.
        version:
          type: integer
          description: Current version for optimistic concurrency control.
        key:
          type: string
          description: User-defined unique identifier.
        customer:
          $ref: '#/components/schemas/Reference'
        interfaceId:
          type: string
          description: Payment identifier as reported by the PSP.
        amountPlanned:
          $ref: '#/components/schemas/Money'
        paymentMethodInfo:
          $ref: '#/components/schemas/PaymentMethodInfo'
        paymentStatus:
          $ref: '#/components/schemas/PaymentStatus'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
          description: List of financial transactions associated with this payment.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the payment was created.
        lastModifiedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the payment was last modified.
    PaymentPagedQueryResponse:
      type: object
      description: Paginated response containing a list of payments.
      required:
      - limit
      - offset
      - count
      - total
      - results
      properties:
        limit:
          type: integer
        offset:
          type: integer
        count:
          type: integer
        total:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
    PaymentDraft:
      type: object
      description: Request body for creating a new payment.
      required:
      - amountPlanned
      properties:
        key:
          type: string
          description: User-defined unique key for the payment.
        customer:
          $ref: '#/components/schemas/Reference'
        interfaceId:
          type: string
          description: PSP payment identifier.
        amountPlanned:
          $ref: '#/components/schemas/Money'
        paymentMethodInfo:
          $ref: '#/components/schemas/PaymentMethodInfo'
        transactions:
          type: array
          items:
            type: object
          description: Initial transactions to create with the payment.
    PaymentMethodInfo:
      type: object
      description: Information about the payment method and PSP used for a payment.
      properties:
        paymentInterface:
          type: string
          description: Identifier of the PSP or payment interface.
        method:
          type: string
          description: Payment method identifier (e.g., 'creditcard', 'paypal').
        name:
          $ref: '#/components/schemas/LocalizedString'
  parameters:
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 20
      description: Maximum number of results to return. Defaults to 20, maximum 500.
    expand:
      name: expand
      in: query
      required: false
      schema:
        type: string
      description: Reference expansion path to inline referenced resources in the response (e.g., 'productType', 'categories[*]').
    projectKey:
      name: projectKey
      in: path
      required: true
      schema:
        type: string
      description: The unique key identifying the commercetools project.
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The system-generated unique identifier of the resource.
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 10000
        default: 0
      description: Number of results to skip for pagination. Maximum 10000.
    where:
      name: where
      in: query
      required: false
      schema:
        type: string
      description: Query predicate string for filtering results. Uses commercetools predicate syntax (e.g., 'customerEmail = "user@example.com"').
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
    Unauthorized:
      description: The request lacked valid authentication credentials.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token obtained from the commercetools authentication service at https://auth.{region}.commercetools.com/oauth/token using client credentials flow.
externalDocs:
  description: commercetools HTTP API Documentation
  url: https://docs.commercetools.com/api