docs: payment and payment collection OAS (#2604)

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
 

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

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"

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

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
 

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 {}

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"

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
 

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
 

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

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 { StoreManagePaymentCollectionSessionRequest } from "./manage-payment-sessions"
-import { AdminRefreshPaymentCollectionSessionRequest } from "./refresh-payment-session"
+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"

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],

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
 

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