Payment-Integration-Api.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "commercetools payment microservice",
    "description": "Control API of the Integration of the commercetools platform with a Payment Service Provider API",
    "version": "1.0.0"
  },
  "host": "(projectId).(pspName)-payments.commercetools.io",
  "schemes": [
    "https",
    "http"
  ],
  "basePath": "/api/v1/",
  "produces": [
    "application/json"
  ],
  "paths": {
    "/commercetools/handle/{resource}/{id}": {
      "get": {
        "summary": "Trigger to force handling of a commerceotols payment object\nSituations that are formally valid in commercetools, but are not supported:\n1. Payments that are referenced by more than one Cart or more than one Order (it is not clear where to take the required data from the Cart/Order from)\n3. Cart / Order and Payment Resource reference differing Customers (it is not clear where to take the Customer data from).\n",
        "parameters": [
          {
            "name": "resource",
            "in": "path",
            "description": "The resource type the given ID refers to.",
            "required": true,
            "type": "string",
            "enum": [
              "payments"
            ]
          },
          {
            "name": "id",
            "in": "path",
            "description": "commercetools id of the Payment that should be handled.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Found the resource and successfully handled it.",
            "schema": {
              "$ref": "#/definitions/PaymentStatus"
            }
          },
          "202": {
            "description": "Found the resource, but the payment API could not immediately complete the necessary actions. Please try again later with the identical request.",
            "schema": {
              "$ref": "#/definitions/PaymentStatus"
            }
          },
          "400": {
            "description": "One of a) This service is not responsible for the payment interface mentioned in the given payment resource. This service is responsible for the PAYONE interface only. b) (reserved for future cases)",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          },
          "403": {
            "description": "The configuration of the service does not allow this request (e.g. not on optional IP whitelist, optional required authentication not passed).",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          },
          "404": {
            "description": "Given resource could not be found.",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        }
      }
    },
    "/FooBar/listen": {
      "get": {
        "summary": "Receives notification / status calls (e.g. webhooks) from the PSP payment interfaces. Completely custom per payment interface implementation.",
        "responses": {
          "default": {
            "description": "PSP specific. Often just a string \"OK\"."
          }
        }
      }
    }
  },
  "definitions": {
    "PaymentStatus": {
      "type": "object",
      "properties": {
        "message": {
          "description": "The description text of the HTTP Status as defined in this api definition (see responses description).",
          "type": "string"
        },
        "handledTransactionState": {
          "description": "If a Transaction was handled, the value of the `state` field of the Transaction that was handled.",
          "type": "string",
          "enum": [
            "Pending",
            "Success",
            "Failure"
          ]
        },
        "redirectRequired": {
          "description": "If the property is true, a redirect is necessary. Specifics are stored in the payment resource (custom fields defined by the standard types).",
          "type": "boolean"
        }
      }
    },
    "Error": {
      "type": "object",
      "required": [
        "statusCode",
        "message",
        "errors"
      ],
      "properties": {
        "statusCode": {
          "description": "The HTTP status code of the overall error situation. Must be equal to the actual HTTP status code sent.",
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "description": "The description of the first error in the \"errors\" list.",
          "type": "string"
        },
        "errors": {
          "description": "The full list of errors that have occurred during processing the API request.",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "description": "a free to choose error code for the specific situation.",
                "type": "string"
              },
              "message": {
                "description": "a matching free text description of the error.  Please be aware that passing error Information from the backend APIs may leak information.",
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}