docs: payment and payment collection OAS (#2604)

This commit is contained in:
Carlos R. L. Rodrigues
2022-11-15 11:30:47 -03:00
committed by GitHub
parent 9e91a50df1
commit 4baa2e0149
14 changed files with 631 additions and 23 deletions

View File

@@ -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

View File

@@ -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

View File

@@ -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"

View File

@@ -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

View File

@@ -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

View File

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

View File

@@ -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"

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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"

View File

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

View File

@@ -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

View File

@@ -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