Updated API from documentation release

api-specs/checkout/api.raml

@@ -3,6 +3,7 @@
 title: commercetools Checkout API
 uses:
   annotations: types/annotations.raml
+  common: types/common.raml
 (annotations.products):
   - Checkout
 version: v1
@@ -15,9 +16,8 @@ baseUriParameters:
     enum:
       - europe-west1.gcp
       - us-central1.gcp
-      - australia-southeast1
     description: |
-      Region
+      [Region](ctp:checkout:type:Region) in which the Checkout application is [hosted](/installing-checkout#regions-and-hosts).
 (annotations.serviceRegions):
   - uri: https://checkout.us-central1.gcp.commercetools.com/
     region: us-central1
@@ -27,9 +27,48 @@ baseUriParameters:
     region: europe-west1
     provider: gcp
     name: Europe (Google Cloud, Belgium)
-  - uri: https://checkout.australia-southeast1.gcp.commercetools.com
-    region: australia-southeast1
-    provider: gcp
-    name: Australia (Google Cloud, Sydney)
 
 types: !include types/types.raml
+
+securitySchemes:
+  oauth_2_0: !include security-schemes/oauth2.raml
+securedBy: [oauth_2_0]
+
+traits:
+  secured_by_manage_payments:
+    securedBy:
+      [oauth_2_0: { scopes: ['manage_checkout_payment_intents:{projectKey}'] }]
+
+/{projectKey}:
+  (annotations.methodName): withProjectKey
+  uriParameters:
+    projectKey:
+      type: string
+      description: Identifier of your Checkout entity and `key` of your [Project](/../api/projects/project#project).
+  /payment-intents:
+    /{paymentId}:
+      (annotations.methodName): withPaymentId
+      uriParameters:
+        paymentId:
+          type: string
+          description: |
+            `id` of the [Payment](/../api/projects/payments).
+      post:
+        is:
+          - secured_by_manage_payments
+        body:
+          type: Payment
+          example: !include ./examples/payments/capturePayment.json
+        description: |
+          Specific Error Codes:
+          - [MultipleActionsNotAllowed](ctp:checkout:type:MultipleActionsNotAllowedError)
+          - [RequiredField](ctp:checkout:type:RequiredFieldError)
+          - [ResourceNotFound](ctp:checkout:type:ResourceNotFoundError)
+        responses:
+          200:
+            body:
+              example: !include ../checkout/examples/payments/capturePaymentResponse.json
+          400:
+            description: The request was invalid.
+            body:
+              type: ErrorResponse

api-specs/checkout/examples/payments/cancelPaymentAction.json

@@ -0,0 +1,3 @@
+{
+  "action": "cancelPayment"
+}

api-specs/checkout/examples/payments/capturePayment.json

@@ -0,0 +1,11 @@
+{
+  "actions": [
+    {
+      "action": "capturePayment",
+      "amount": {
+        "centAmount": 10000,
+        "currencyCode": "EUR"
+      }
+    }
+  ]
+}

api-specs/checkout/examples/payments/capturePaymentAction.json

@@ -0,0 +1,7 @@
+{
+  "action": "capturePayment",
+  "amount": {
+    "centAmount": 10000,
+    "currencyCode": "EUR"
+  }
+}

api-specs/checkout/examples/payments/capturePaymentResponse.json

@@ -0,0 +1 @@
+{}

api-specs/checkout/examples/payments/refundPaymentAction.json

@@ -0,0 +1,7 @@
+{
+  "action": "refundPayment",
+  "amount": {
+    "centAmount": 10000,
+    "currencyCode": "EUR"
+  }
+}

api-specs/checkout/types/annotations.raml

@@ -12,6 +12,8 @@ annotationTypes:
     allowedTargets:
       - Library
     type: string
+  beta:
+    type: boolean
   enumDescriptions:
     description: |
       Allows to describe the values of an enum type.

api-specs/checkout/types/common.raml

@@ -0,0 +1,63 @@
+#%RAML 1.0 Library
+usage: Common data types.
+(annotations.package): common
+(annotations.beta): true
+
+uses:
+  annotations: annotations.raml
+
+types:
+  Region:
+    description: |
+      The Region in which the Checkout application is [hosted](/../checkout/installing-checkout#regions-and-hosts).
+    enum:
+      - europe-west1.gcp
+      - us-central1.gcp
+    (annotations.enumDescriptions):
+      europe-west1.gcp: |
+        for Europe (Google Cloud, Belgium)
+      us-central1.gcp: |
+        for North America (Google Cloud, Iowa)
+  Amount:
+    description: |
+      The amount related to a [payment action](ctp:checkout:type:PaymentAction).
+    properties:
+      centAmount:
+        type: integer
+        description: |
+          Amount in the smallest indivisible unit of a currency, such as:
+
+          * Cents for EUR and USD, pence for GBP, or centime for CHF (5 CHF is specified as `500`).
+          * The value in the major unit for currencies without minor units, like JPY (5 JPY is specified as `5`).
+      currencyCode:
+        type: string
+        description: |
+          Currency code compliant to [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).
+        pattern: ^[A-Z]{3}$
+  PaymentOperation:
+    type: string
+    description: |
+      The possible values for a [payment action](ctp:checkout:type:PaymentAction).
+    (annotations.enumDescriptions):
+      capturePayment: |
+        [Captures](ctp:checkout:type:CapturePaymentAction) the given [Payment](/../api/projects/payments#payment) amount.
+      refundPayment: |
+        [Refunds](ctp:checkout:type:RefundPaymentAction) the given Payment amount.
+      cancelPayment: |
+        [Cancels](ctp:checkout:type:CancelPaymentAction) an authorized Payment.
+    enum:
+      - capturePayment
+      - refundPayment
+      - cancelPayment
+  PaymentAction:
+    description: |
+      Depending on the action specified, Checkout requests the [Payment Service Provider](/../checkout/configuring-checkout#supported-payment-service-providers) to capture, refund, or cancel the authorization for the given Payment.
+    properties:
+      action:
+        type: PaymentOperation
+        description: |
+          Action to execute for the given Payment.
+      amount?:
+        type: Amount
+        description: |
+          Amount to be captured or refunded.

api-specs/checkout/types/payments/cancelPaymentAction.raml

@@ -0,0 +1,15 @@
+#%RAML 1.0 DataType
+(annotations.package): Payments
+(annotations.beta): true
+type: object
+displayName: CancelPaymentAction
+discriminator: action
+discriminatorValue: cancelPayment
+example: !include ../../../checkout/examples/payments/cancelPaymentAction.json
+description: |
+  Requests to [cancel the authorization](/payments-lifecycle#authorization-cancellation) for a Payment. Checkout will cancel the [Payment](/../api/projects/payments#payment) and will request the PSP to proceed with the financial process to cancel the authorization.
+
+  You cannot request to cancel the authorization for a Payment that has already been [captured](/payments-lifecycle#payment-capture).
+properties:
+  action:
+    type: string

api-specs/checkout/types/payments/capturePaymentAction.raml

@@ -0,0 +1,17 @@
+#%RAML 1.0 DataType
+(annotations.package): Payments
+(annotations.beta): true
+type: object
+displayName: CapturePaymentAction
+discriminator: action
+discriminatorValue: capturePayment
+example: !include ../../../checkout/examples/payments/capturePaymentAction.json
+description: |
+  Requests to [capture](/payments-lifecycle#payment-capture) the given amount from the customer. Checkout will request the PSP to proceed with the financial process to capture the amount.
+properties:
+  action:
+    type: string
+  amount:
+    description: |
+      Amount to be captured. It must be less than or equal to the [authorized](/payments-lifecycle#authorization) amount.
+    type: common.Amount

api-specs/checkout/types/payments/error/ErrorObject.raml

@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(annotations.package): error
+(annotations.beta): true
+type: object
+displayName: ErrorObject
+discriminator: code
+description: This is the representation of a single error.
+properties:
+  code:
+    type: string
+    description: |
+      Error identifier.
+  message:
+    type: string
+    description: |
+      Plain text description of the cause of the error.

api-specs/checkout/types/payments/error/GeneralError.raml

@@ -0,0 +1,15 @@
+#%RAML 1.0 DataType
+(annotations.package): error
+(annotations.beta): true
+type: ErrorObject
+displayName: GeneralError
+discriminatorValue: General
+description: |
+  Returned when a server-side problem occurs. If you encounter this error, report it using the [Support Portal](https://commercetools.atlassian.net/servicedesk/customer/portal/30).
+properties:
+  code:
+    type: string
+  message:
+    type: string
+    description: |
+      Description about any known details of the problem, for example, `"Write operations are temporarily unavailable"`.

api-specs/checkout/types/payments/error/MultipleActionsNotAllowedError.raml

@@ -0,0 +1,15 @@
+#%RAML 1.0 DataType
+(annotations.package): error
+(annotations.beta): true
+type: ErrorObject
+displayName: MultipleActionsNotAllowedError
+discriminatorValue: MultipleActionsNotAllowed
+description: |
+  Returned when `actions` in the request body contains more than one object.
+properties:
+  code:
+    type: string
+  message:
+    type: string
+    description: |
+      `"Actions accepts only one action at time. Array size must be 1."`

api-specs/checkout/types/payments/error/RequiredFieldError.raml

@@ -0,0 +1,19 @@
+#%RAML 1.0 DataType
+(annotations.package): error
+(annotations.beta): true
+type: ErrorObject
+displayName: RequiredFieldError
+discriminatorValue: RequiredField
+description: |
+  Returned when a value is not defined for a required field.
+properties:
+  code:
+    type: string
+  message:
+    type: string
+    description: |
+      `"A value is required for field $field."`
+  field:
+    type: string
+    description: |
+      Name of the field missing the value.

api-specs/checkout/types/payments/error/ResourceNotFoundError.raml

@@ -0,0 +1,15 @@
+#%RAML 1.0 DataType
+(annotations.package): error
+(annotations.beta): true
+type: ErrorObject
+displayName: ResourceNotFoundError
+discriminatorValue: ResourceNotFound
+description: |
+  Returned when the resource addressed by the request URL does not exist.
+properties:
+  code:
+    type: string
+  message:
+    type: string
+    description: |
+      `"The Resource with ID $resourceId was not found."`

api-specs/checkout/types/payments/payment.raml

@@ -0,0 +1,12 @@
+#%RAML 1.0 DataType
+(annotations.package): Payments
+(annotations.beta): true
+type: object
+displayName: Payment
+properties:
+  actions:
+    type: common.PaymentAction[]
+    minItems: 1
+    maxItems: 1
+    description: |
+      Action to execute for the given Payment.

api-specs/checkout/types/payments/paymentActionAmount.raml

@@ -0,0 +1,8 @@
+#%RAML 1.0 DataType
+(annotations.package): Payments
+(annotations.beta): true
+type: object
+displayName: Amount
+properties:
+  centAmount: number
+  currencyCode: string

api-specs/checkout/types/payments/refundPaymentAction.raml

@@ -0,0 +1,17 @@
+#%RAML 1.0 DataType
+(annotations.package): Payments
+(annotations.beta): true
+type: object
+displayName: RefundPaymentAction
+discriminator: action
+discriminatorValue: refundPayment
+example: !include ../../../checkout/examples/payments/refundPaymentAction.json
+description: |
+  Requests to [refund](/payments-lifecycle#refund) the given amount to the customer. Checkout will request the PSP to proceed with the financial process to refund the amount.
+properties:
+  action:
+    type: string
+  amount?:
+    description: |
+      Amount to be refunded. It must be less than or equal to the [captured](/payments-lifecycle#payment-capture) amount.
+    type: common.Amount

api-specs/checkout/types/types.raml

@@ -1,3 +1,4 @@
+# Responses
 ResponseMessage: !include responses/ResponseMessage.raml
 AdyenBadConfig: !include responses/AdyenBadConfig.raml
 AdyenInitError: !include responses/AdyenInitError.raml
@@ -24,3 +25,14 @@ UnavailableLocale: !include responses/UnavailableLocale.raml
 DeprecatedFields: !include responses/DeprecatedFields.raml
 OrderCreationError: !include responses/OrderCreationError.raml
 CartWithExistingPayment: !include responses/CartWithExistingPayment.raml
+# payments
+CapturePaymentAction: !include payments/capturePaymentAction.raml
+RefundPaymentAction: !include payments/refundPaymentAction.raml
+CancelPaymentAction: !include payments/cancelPaymentAction.raml
+Payment: !include payments/payment.raml
+# Payment Errors
+ErrorObject: !include payments/error/ErrorObject.raml
+GeneralError: !include payments/error/GeneralError.raml
+MultipleActionsNotAllowedError: !include payments/error/MultipleActionsNotAllowedError.raml
+RequiredFieldError: !include payments/error/RequiredFieldError.raml
+ResourceNotFoundError: !include payments/error/ResourceNotFoundError.raml