From 6fdddfe25400a00a9b38068eabe18331d216fc82 Mon Sep 17 00:00:00 2001 From: "ct-sdks[bot]" <153784748+ct-sdks[bot]@users.noreply.github.com> Date: Tue, 9 Jan 2024 07:43:50 +0000 Subject: [PATCH] Updated API from documentation release --- .../DiscountCodeSetValidUntilAction.json | 2 +- api-specs/checkout/api.raml | 51 +++++++++++++-- .../payments/cancelPaymentAction.json | 3 + .../examples/payments/capturePayment.json | 11 ++++ .../payments/capturePaymentAction.json | 7 +++ .../payments/capturePaymentResponse.json | 1 + .../payments/refundPaymentAction.json | 7 +++ api-specs/checkout/types/annotations.raml | 2 + api-specs/checkout/types/common.raml | 63 +++++++++++++++++++ .../types/payments/cancelPaymentAction.raml | 15 +++++ .../types/payments/capturePaymentAction.raml | 17 +++++ .../types/payments/error/ErrorObject.raml | 16 +++++ .../types/payments/error/GeneralError.raml | 15 +++++ .../error/MultipleActionsNotAllowedError.raml | 15 +++++ .../payments/error/RequiredFieldError.raml | 19 ++++++ .../payments/error/ResourceNotFoundError.raml | 15 +++++ .../checkout/types/payments/payment.raml | 12 ++++ .../types/payments/paymentActionAmount.raml | 8 +++ .../types/payments/refundPaymentAction.raml | 17 +++++ api-specs/checkout/types/types.raml | 12 ++++ 20 files changed, 301 insertions(+), 7 deletions(-) create mode 100644 api-specs/checkout/examples/payments/cancelPaymentAction.json create mode 100644 api-specs/checkout/examples/payments/capturePayment.json create mode 100644 api-specs/checkout/examples/payments/capturePaymentAction.json create mode 100644 api-specs/checkout/examples/payments/capturePaymentResponse.json create mode 100644 api-specs/checkout/examples/payments/refundPaymentAction.json create mode 100644 api-specs/checkout/types/common.raml create mode 100644 api-specs/checkout/types/payments/cancelPaymentAction.raml create mode 100644 api-specs/checkout/types/payments/capturePaymentAction.raml create mode 100644 api-specs/checkout/types/payments/error/ErrorObject.raml create mode 100644 api-specs/checkout/types/payments/error/GeneralError.raml create mode 100644 api-specs/checkout/types/payments/error/MultipleActionsNotAllowedError.raml create mode 100644 api-specs/checkout/types/payments/error/RequiredFieldError.raml create mode 100644 api-specs/checkout/types/payments/error/ResourceNotFoundError.raml create mode 100644 api-specs/checkout/types/payments/payment.raml create mode 100644 api-specs/checkout/types/payments/paymentActionAmount.raml create mode 100644 api-specs/checkout/types/payments/refundPaymentAction.raml diff --git a/api-specs/api/examples/DiscountCode/DiscountCodeSetValidUntilAction.json b/api-specs/api/examples/DiscountCode/DiscountCodeSetValidUntilAction.json index 3c33bc8f1..c7f1188ae 100644 --- a/api-specs/api/examples/DiscountCode/DiscountCodeSetValidUntilAction.json +++ b/api-specs/api/examples/DiscountCode/DiscountCodeSetValidUntilAction.json @@ -1,4 +1,4 @@ { "action": "setValidUntil", - "validFrom": "2018-10-12T14:00:00.000Z" + "validUntil": "2018-10-12T14:00:00.000Z" } diff --git a/api-specs/checkout/api.raml b/api-specs/checkout/api.raml index 60901aa85..a3e9879cc 100644 --- a/api-specs/checkout/api.raml +++ b/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 diff --git a/api-specs/checkout/examples/payments/cancelPaymentAction.json b/api-specs/checkout/examples/payments/cancelPaymentAction.json new file mode 100644 index 000000000..e630f38b9 --- /dev/null +++ b/api-specs/checkout/examples/payments/cancelPaymentAction.json @@ -0,0 +1,3 @@ +{ + "action": "cancelPayment" +} diff --git a/api-specs/checkout/examples/payments/capturePayment.json b/api-specs/checkout/examples/payments/capturePayment.json new file mode 100644 index 000000000..6ec86e51b --- /dev/null +++ b/api-specs/checkout/examples/payments/capturePayment.json @@ -0,0 +1,11 @@ +{ + "actions": [ + { + "action": "capturePayment", + "amount": { + "centAmount": 10000, + "currencyCode": "EUR" + } + } + ] +} diff --git a/api-specs/checkout/examples/payments/capturePaymentAction.json b/api-specs/checkout/examples/payments/capturePaymentAction.json new file mode 100644 index 000000000..5daa0341a --- /dev/null +++ b/api-specs/checkout/examples/payments/capturePaymentAction.json @@ -0,0 +1,7 @@ +{ + "action": "capturePayment", + "amount": { + "centAmount": 10000, + "currencyCode": "EUR" + } +} diff --git a/api-specs/checkout/examples/payments/capturePaymentResponse.json b/api-specs/checkout/examples/payments/capturePaymentResponse.json new file mode 100644 index 000000000..0967ef424 --- /dev/null +++ b/api-specs/checkout/examples/payments/capturePaymentResponse.json @@ -0,0 +1 @@ +{} diff --git a/api-specs/checkout/examples/payments/refundPaymentAction.json b/api-specs/checkout/examples/payments/refundPaymentAction.json new file mode 100644 index 000000000..d7da448c6 --- /dev/null +++ b/api-specs/checkout/examples/payments/refundPaymentAction.json @@ -0,0 +1,7 @@ +{ + "action": "refundPayment", + "amount": { + "centAmount": 10000, + "currencyCode": "EUR" + } +} diff --git a/api-specs/checkout/types/annotations.raml b/api-specs/checkout/types/annotations.raml index e1b200b07..b93c1d8e1 100644 --- a/api-specs/checkout/types/annotations.raml +++ b/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. diff --git a/api-specs/checkout/types/common.raml b/api-specs/checkout/types/common.raml new file mode 100644 index 000000000..9f51cf29f --- /dev/null +++ b/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. diff --git a/api-specs/checkout/types/payments/cancelPaymentAction.raml b/api-specs/checkout/types/payments/cancelPaymentAction.raml new file mode 100644 index 000000000..d4294687c --- /dev/null +++ b/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 diff --git a/api-specs/checkout/types/payments/capturePaymentAction.raml b/api-specs/checkout/types/payments/capturePaymentAction.raml new file mode 100644 index 000000000..9860bab34 --- /dev/null +++ b/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 diff --git a/api-specs/checkout/types/payments/error/ErrorObject.raml b/api-specs/checkout/types/payments/error/ErrorObject.raml new file mode 100644 index 000000000..fd8f621d0 --- /dev/null +++ b/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. diff --git a/api-specs/checkout/types/payments/error/GeneralError.raml b/api-specs/checkout/types/payments/error/GeneralError.raml new file mode 100644 index 000000000..96678c1c0 --- /dev/null +++ b/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"`. diff --git a/api-specs/checkout/types/payments/error/MultipleActionsNotAllowedError.raml b/api-specs/checkout/types/payments/error/MultipleActionsNotAllowedError.raml new file mode 100644 index 000000000..17266846a --- /dev/null +++ b/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."` diff --git a/api-specs/checkout/types/payments/error/RequiredFieldError.raml b/api-specs/checkout/types/payments/error/RequiredFieldError.raml new file mode 100644 index 000000000..fcd6ffc1d --- /dev/null +++ b/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. diff --git a/api-specs/checkout/types/payments/error/ResourceNotFoundError.raml b/api-specs/checkout/types/payments/error/ResourceNotFoundError.raml new file mode 100644 index 000000000..61ecc9e34 --- /dev/null +++ b/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."` diff --git a/api-specs/checkout/types/payments/payment.raml b/api-specs/checkout/types/payments/payment.raml new file mode 100644 index 000000000..4afc009fb --- /dev/null +++ b/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. diff --git a/api-specs/checkout/types/payments/paymentActionAmount.raml b/api-specs/checkout/types/payments/paymentActionAmount.raml new file mode 100644 index 000000000..fb4f7e9dc --- /dev/null +++ b/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 diff --git a/api-specs/checkout/types/payments/refundPaymentAction.raml b/api-specs/checkout/types/payments/refundPaymentAction.raml new file mode 100644 index 000000000..baff7427a --- /dev/null +++ b/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 diff --git a/api-specs/checkout/types/types.raml b/api-specs/checkout/types/types.raml index 57b3404d0..bcba09ba3 100644 --- a/api-specs/checkout/types/types.raml +++ b/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