From 4baa2e014986a47f8ad53ce8cb55ddf72e565790 Mon Sep 17 00:00:00 2001 From: "Carlos R. L. Rodrigues" <37986729+carlos-r-l-rodrigues@users.noreply.github.com> Date: Tue, 15 Nov 2022 11:30:47 -0300 Subject: [PATCH] docs: payment and payment collection OAS (#2604) --- .../delete-payment-collection.ts | 52 ++++++++++++ .../get-payment-collection.ts | 53 ++++++++++++ .../routes/admin/payment-collections/index.ts | 10 +++ .../update-payment-collection.ts | 68 ++++++++++++++++ .../routes/admin/payments/capture-payment.ts | 51 ++++++++++++ .../api/routes/admin/payments/get-payment.ts | 53 +++++++++++- .../src/api/routes/admin/payments/index.ts | 9 +++ .../routes/admin/payments/refund-payment.ts | 78 ++++++++++++++++++ .../authorize-payment-collection.ts | 51 ++++++++++++ .../get-payment-collection.ts | 53 ++++++++++++ .../routes/store/payment-collections/index.ts | 17 +++- .../manage-payment-sessions.ts | 81 ++++++++++++++++++- .../refresh-payment-session.ts | 66 ++++++++++++++- .../medusa/src/models/payment-collection.ts | 12 --- 14 files changed, 631 insertions(+), 23 deletions(-) diff --git a/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts index e64acd61e6..551005cd67 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts @@ -1,5 +1,57 @@ import { PaymentCollectionService } from "../../../../services" +/** + * @oas [delete] /payment-collections/{id} + * operationId: "DeletePaymentCollectionsPaymentCollection" + * summary: "Delete a Payment Collection" + * description: "Deletes a Payment Collection" + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the Payment Collection to delete. + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.delete(payment_collection_id) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) + * - lang: Shell + * label: cURL + * source: | + * curl --location --request DELETE 'https://medusa-url.com/admin/payment-collections/{id}' \ + * --header 'Authorization: Bearer {api_token}' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - PaymentCollection + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * id: + * type: string + * description: The ID of the deleted Payment Collection. + * object: + * type: string + * description: The type of the object that was deleted. + * format: payment_collection + * deleted: + * type: boolean + * description: Whether or not the Payment Collection was deleted. + * default: true + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + */ export default async (req, res) => { const { id } = req.params diff --git a/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts index a450ba8a7f..f2535e41ba 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts @@ -1,6 +1,59 @@ import { PaymentCollectionService } from "../../../../services" import { FindParams } from "../../../../types/common" +/** + * @oas [get] /payment-collections/{id} + * operationId: "GetPaymentCollectonsPaymentCollection" + * summary: "Retrieve an PaymentCollection" + * description: "Retrieves a PaymentCollection." + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the PaymentCollection. + * - (query) expand {string} Comma separated list of relations to include in the results. + * - (query) fields {string} Comma separated list of fields to include in the results. + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.retrieve(paymentCollectionId) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + * - lang: Shell + * label: cURL + * source: | + * curl --location --request GET 'https://medusa-url.com/admin/payment-collections/{id}' \ + * --header 'Authorization: Bearer {api_token}' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - PaymentCollection + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment_collection: + * $ref: "#/components/schemas/payment_collection" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { const { id } = req.params const retrieveConfig = req.retrieveConfig diff --git a/packages/medusa/src/api/routes/admin/payment-collections/index.ts b/packages/medusa/src/api/routes/admin/payment-collections/index.ts index 441fb5b3db..774fa186dc 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/index.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/index.ts @@ -9,6 +9,7 @@ import { isFeatureFlagEnabled } from "../../../middlewares/feature-flag-enabled" import { GetPaymentCollectionsParams } from "./get-payment-collection" import { AdminUpdatePaymentCollectionRequest } from "./update-payment-collection" +import { PaymentCollection } from "../../../../models" const route = Router() @@ -62,5 +63,14 @@ export const defaulPaymentCollectionRelations = [ "payments", ] +export type AdminPaymentCollectionRes = { + payment_collection: PaymentCollection +} +export type AdminPaymentCollectionDeleteRes = { + id: string + object: "payment_collection" + deleted: boolean +} + export * from "./get-payment-collection" export * from "./update-payment-collection" diff --git a/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts index 9b06cbfded..34c2ca7d81 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts @@ -3,6 +3,74 @@ import { IsObject, IsOptional, IsString } from "class-validator" import { EntityManager } from "typeorm" import { PaymentCollectionService } from "../../../../services" +/** + * @oas [post] /payment-collections/{id} + * operationId: "PostPaymentCollectionsPaymentCollection" + * summary: "Updates a PaymentCollection" + * description: "Updates a PaymentCollection." + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the PaymentCollection. + * requestBody: + * content: + * application/json: + * schema: + * properties: + * description: + * description: An optional description to create or update the payment collection. + * type: string + * metadata: + * description: An optional set of key-value pairs to hold additional information. + * type: object + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.update(payment_collection_id, { + * description: "Description of payCol" + * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + * - lang: Shell + * label: cURL + * source: | + * curl --location --request POST 'https://medusa-url.com/admin/payment-collections/{id}' \ + * --header 'Authorization: Bearer {api_token}' \ + * --header 'Content-Type: application/json' \ + * --data-raw '{ + * "description": "Description of payCol" + * }' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - PaymentCollection + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment_collection: + * $ref: "#/components/schemas/payment_collection" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { const { id } = req.params const data = req.validatedBody as AdminUpdatePaymentCollectionRequest diff --git a/packages/medusa/src/api/routes/admin/payments/capture-payment.ts b/packages/medusa/src/api/routes/admin/payments/capture-payment.ts index b5a95e10a9..38489a45d1 100644 --- a/packages/medusa/src/api/routes/admin/payments/capture-payment.ts +++ b/packages/medusa/src/api/routes/admin/payments/capture-payment.ts @@ -1,5 +1,56 @@ import { PaymentService } from "../../../../services" +/** + * @oas [post] /payments/{id}/capture + * operationId: "PostPaymentsPaymentCapture" + * summary: "Capture a Payment" + * description: "Captures a Payment." + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the Payment. + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.payments.capturePayment(payment_id) + * .then(({ payment }) => { + * console.log(payment.id); + * }); + * - lang: Shell + * label: cURL + * source: | + * curl --location --request POST 'https://medusa-url.com/admin/payments/{id}/capture' \ + * --header 'Authorization: Bearer {api_token}' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - Payment + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment: + * $ref: "#/components/schemas/payment" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { const { id } = req.params diff --git a/packages/medusa/src/api/routes/admin/payments/get-payment.ts b/packages/medusa/src/api/routes/admin/payments/get-payment.ts index 434894327e..fde5fde561 100644 --- a/packages/medusa/src/api/routes/admin/payments/get-payment.ts +++ b/packages/medusa/src/api/routes/admin/payments/get-payment.ts @@ -1,6 +1,57 @@ import { PaymentService } from "../../../../services" import { FindParams } from "../../../../types/common" +/** + * @oas [get] /payments/{id} + * operationId: "GetPaymentsPayment" + * summary: "Get Payment details" + * description: "Retrieves the Payment details" + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the Payment. + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.payments.retrieve(payment_id) + * .then(({ payment }) => { + * console.log(payment.id); + * }); + * - lang: Shell + * label: cURL + * source: | + * curl --location --request GET 'https://medusa-url.com/admin/payments/{id}' \ + * --header 'Authorization: Bearer {api_token}' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - Payment + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment: + * $ref: "#/components/schemas/payment" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { const { id } = req.params const retrieveConfig = req.retrieveConfig @@ -9,7 +60,7 @@ export default async (req, res) => { const payment = await paymentService.retrieve(id, retrieveConfig) - res.status(200).json({ payment: payment }) + res.status(200).json({ payment }) } export class GetPaymentsParams extends FindParams {} diff --git a/packages/medusa/src/api/routes/admin/payments/index.ts b/packages/medusa/src/api/routes/admin/payments/index.ts index d750505861..600a5db8fb 100644 --- a/packages/medusa/src/api/routes/admin/payments/index.ts +++ b/packages/medusa/src/api/routes/admin/payments/index.ts @@ -9,6 +9,7 @@ import { isFeatureFlagEnabled } from "../../../middlewares/feature-flag-enabled" import { GetPaymentsParams } from "./get-payment" import { AdminPostPaymentRefundsReq } from "./refund-payment" +import { Payment, Refund } from "../../../../models" const route = Router() @@ -53,5 +54,13 @@ export const defaultPaymentFields = [ "metadata", ] +export type AdminPaymentRes = { + payment: Payment +} + +export type AdminRefundRes = { + refund: Refund +} + export * from "./get-payment" export * from "./refund-payment" diff --git a/packages/medusa/src/api/routes/admin/payments/refund-payment.ts b/packages/medusa/src/api/routes/admin/payments/refund-payment.ts index 4c872a5b29..cffe0cdf1e 100644 --- a/packages/medusa/src/api/routes/admin/payments/refund-payment.ts +++ b/packages/medusa/src/api/routes/admin/payments/refund-payment.ts @@ -9,6 +9,84 @@ import { RefundReason } from "../../../../models" import { PaymentService } from "../../../../services" +/** + * @oas [post] /payments/{id}/refund + * operationId: "PostPaymentsPaymentRefunds" + * summary: "Create a Refund" + * description: "Issues a Refund." + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the Payment. + * requestBody: + * content: + * application/json: + * schema: + * required: + * - amount + * - reason + * properties: + * amount: + * description: The amount to refund. + * type: integer + * reason: + * description: The reason for the Refund. + * type: string + * note: + * description: A note with additional details about the Refund. + * type: string + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.payments.refundPayment(payment_id, { + * amount: 1000, + * reason: 'return', + * note: 'Do not like it', + * }) + * .then(({ payment }) => { + * console.log(payment.id); + * }); + * - lang: Shell + * label: cURL + * source: | + * curl --location --request POST 'https://medusa-url.com/admin/payments/pay_123/refund' \ + * --header 'Authorization: Bearer {api_token}' \ + * --header 'Content-Type: application/json' \ + * --data-raw '{ + * "amount": 1000, + * "reason": "return", + * "note": "Do not like it" + * }' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - Payment + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * refund: + * $ref: "#/components/schemas/refund" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { const { id } = req.params diff --git a/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-collection.ts b/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-collection.ts index 4b662d5068..ceb89674e3 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-collection.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-collection.ts @@ -1,5 +1,56 @@ import { PaymentCollectionService } from "../../../../services" +/** + * @oas [post] /payment-collections/{id}/authorize + * operationId: "PostPaymentCollectionsAuthorize" + * summary: "Authorize a Payment Collections" + * description: "Authorizes a Payment Collections." + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the Payment Collections. + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.authorize(payment_id) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }); + * - lang: Shell + * label: cURL + * source: | + * curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/authorize' \ + * --header 'Authorization: Bearer {api_token}' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - Payment + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment_collection: + * $ref: "#/components/schemas/payment_collection" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { const { payment_id } = req.params diff --git a/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts b/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts index a450ba8a7f..c28212d538 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts @@ -1,6 +1,59 @@ import { PaymentCollectionService } from "../../../../services" import { FindParams } from "../../../../types/common" +/** + * @oas [get] /payment-collections/{id} + * operationId: "GetPaymentCollectonsPaymentCollection" + * summary: "Retrieve an PaymentCollection" + * description: "Retrieves a PaymentCollection." + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the PaymentCollection. + * - (query) expand {string} Comma separated list of relations to include in the results. + * - (query) fields {string} Comma separated list of fields to include in the results. + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.retrieve(paymentCollectionId) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + * - lang: Shell + * label: cURL + * source: | + * curl --location --request GET 'https://medusa-url.com/store/payment-collections/{id}' \ + * --header 'Authorization: Bearer {api_token}' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - PaymentCollection + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment_collection: + * $ref: "#/components/schemas/payment_collection" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { const { id } = req.params const retrieveConfig = req.retrieveConfig diff --git a/packages/medusa/src/api/routes/store/payment-collections/index.ts b/packages/medusa/src/api/routes/store/payment-collections/index.ts index 39deb89612..63468e44c6 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/index.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/index.ts @@ -8,9 +8,10 @@ import middlewares, { import OrderEditingFeatureFlag from "../../../../loaders/feature-flags/order-editing" import { isFeatureFlagEnabled } from "../../../middlewares/feature-flag-enabled" -import { AdminManagePaymentCollectionSessionRequest } from "./manage-payment-sessions" -import { AdminRefreshPaymentCollectionSessionRequest } from "./refresh-payment-session" +import { StoreManagePaymentCollectionSessionRequest } from "./manage-payment-sessions" +import { StoreRefreshPaymentCollectionSessionRequest } from "./refresh-payment-session" import { GetPaymentCollectionsParams } from "./get-payment-collection" +import { PaymentCollection, PaymentSession } from "../../../../models" const route = Router() @@ -38,13 +39,13 @@ export default (app, container) => { route.post( "/:id/sessions", - transformBody(AdminManagePaymentCollectionSessionRequest), + transformBody(StoreManagePaymentCollectionSessionRequest), middlewares.wrap(require("./manage-payment-sessions").default) ) route.post( "/:id/sessions/:session_id/refresh", - transformBody(AdminRefreshPaymentCollectionSessionRequest), + transformBody(StoreRefreshPaymentCollectionSessionRequest), middlewares.wrap(require("./refresh-payment-session").default) ) @@ -65,6 +66,14 @@ export const defaultPaymentCollectionFields = [ export const defaulPaymentCollectionRelations = ["region", "payment_sessions"] +export type StorePaymentCollectionRes = { + payment_collection: PaymentCollection +} + +export type StorePaymentCollectionSessionRes = { + payment_session: PaymentSession +} + export * from "./get-payment-collection" export * from "./manage-payment-sessions" export * from "./refresh-payment-session" diff --git a/packages/medusa/src/api/routes/store/payment-collections/manage-payment-sessions.ts b/packages/medusa/src/api/routes/store/payment-collections/manage-payment-sessions.ts index 45f5d9f05f..882b8a73dc 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/manage-payment-sessions.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/manage-payment-sessions.ts @@ -4,8 +4,85 @@ import { IsType } from "../../../../utils/validators/is-type" import { EntityManager } from "typeorm" import { PaymentCollectionService } from "../../../../services" +/** + * @oas [post] /payment-collections/{id}/sessions + * operationId: "PostPaymentCollectionsSessions" + * summary: "Manage Payment Sessions from Payment Collections" + * description: "Manages Payment Sessions from Payment Collections." + * x-authenticated: true + * parameters: + * - (path) id=* {string} The ID of the Payment Collections. + * requestBody: + * content: + * application/json: + * schema: + * properties: + * sessions: + * description: "An array or a single entry of payment sessions related to the Payment Collection. If the session_id is not provided the existing sessions not present will be deleted and the provided ones will be created." + * type: array + * items: + * required: + * - provider_id + * - customer_id + * - amount + * properties: + * provider_id: + * type: string + * description: The ID of the Payment Provider. + * customer_id: + * type: string + * description: "The ID of the Customer." + * amount: + * type: integer + * description: "The amount ." + * session_id: + * type: string + * description: "The ID of the Payment Session to be updated." + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.sessions(payment_id, payload) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }); + * - lang: Shell + * label: cURL + * source: | + * curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions' \ + * --header 'Authorization: Bearer {api_token}' + * security: + * - api_token: [] + * - cookie_auth: [] + * tags: + * - Payment + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment_collection: + * $ref: "#/components/schemas/payment_collection" + * "400": + * $ref: "#/components/responses/400_error" + * "401": + * $ref: "#/components/responses/unauthorized" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { - const data = req.validatedBody as AdminManagePaymentCollectionSessionRequest + const data = req.validatedBody as StoreManagePaymentCollectionSessionRequest const { id } = req.params const paymentCollectionService: PaymentCollectionService = req.scope.resolve( @@ -40,7 +117,7 @@ export class PaymentCollectionSessionInputRequest { session_id?: string } -export class AdminManagePaymentCollectionSessionRequest { +export class StoreManagePaymentCollectionSessionRequest { @IsType([ PaymentCollectionSessionInputRequest, [PaymentCollectionSessionInputRequest], diff --git a/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts b/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts index 1544dabbb3..68a59bde79 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts @@ -3,8 +3,66 @@ import { IsInt, IsNotEmpty, IsString } from "class-validator" import { EntityManager } from "typeorm" import { PaymentCollectionService } from "../../../../services" +/** + * @oas [post] /payment-collections/{id}/sessions/{session_id}/refresh + * operationId: PostPaymentCollectionsPaymentCollectionPaymentSessionsSession + * summary: Refresh a Payment Session + * description: "Refreshes a Payment Session to ensure that it is in sync with the Payment Collection." + * parameters: + * - (path) id=* {string} The id of the PaymentCollection. + * - (path) session_id=* {string} The id of the Payment Session to be refreshed. + * requestBody: + * content: + * application/json: + * schema: + * required: + * - provider_id + * - customer_id + * properties: + * provider_id: + * description: The Payment Provider id. + * type: string + * customer_id: + * description: The Customer id. + * type: string + * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.paymentCollections.refreshPaymentSession(payment_collection_id, session_id, payload) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }); + * - lang: Shell + * label: cURL + * source: | + * curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}/refresh' + * tags: + * - PaymentCollection + * responses: + * 200: + * description: OK + * content: + * application/json: + * schema: + * properties: + * payment_session: + * $ref: "#/components/schemas/payment_session" + * "400": + * $ref: "#/components/responses/400_error" + * "404": + * $ref: "#/components/responses/not_found_error" + * "409": + * $ref: "#/components/responses/invalid_state_error" + * "422": + * $ref: "#/components/responses/invalid_request_error" + * "500": + * $ref: "#/components/responses/500_error" + */ export default async (req, res) => { - const data = req.validatedBody as AdminRefreshPaymentCollectionSessionRequest + const data = req.validatedBody as StoreRefreshPaymentCollectionSessionRequest const { id, session_id } = req.params const paymentCollectionService: PaymentCollectionService = req.scope.resolve( @@ -12,7 +70,7 @@ export default async (req, res) => { ) const manager: EntityManager = req.scope.resolve("manager") - const paymentCollection = await manager.transaction( + const paymentSession = await manager.transaction( async (transactionManager) => { return await paymentCollectionService .withTransaction(transactionManager) @@ -20,10 +78,10 @@ export default async (req, res) => { } ) - res.status(200).json({ payment_collection: paymentCollection }) + res.status(200).json({ payment_session: paymentSession }) } -export class AdminRefreshPaymentCollectionSessionRequest { +export class StoreRefreshPaymentCollectionSessionRequest { @IsString() provider_id: string diff --git a/packages/medusa/src/models/payment-collection.ts b/packages/medusa/src/models/payment-collection.ts index 57fc9adb98..5f9701291e 100644 --- a/packages/medusa/src/models/payment-collection.ts +++ b/packages/medusa/src/models/payment-collection.ts @@ -101,7 +101,6 @@ export class PaymentCollection extends SoftDeletableEntity { } } - /** * @schema payment_collection * title: "Payment Collection" @@ -132,12 +131,7 @@ export class PaymentCollection extends SoftDeletableEntity { * - awaiting * - authorized * - partially_authorized - * - captured - * - partially_captured - * - refunded - * - partially_refunded * - canceled - * - requires_action * description: * type: string * description: Description of the payment collection @@ -147,12 +141,6 @@ export class PaymentCollection extends SoftDeletableEntity { * authorized_amount: * type: number * description: Authorized amount of the payment collection. - * captured_amount: - * type: number - * description: Captured amount of the payment collection. - * refunded_amount: - * type: number - * description: Refunded amount of the payment collection. * region_id: * type: string * description: The region's ID