diff --git a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md b/docs/content/advanced/backend/payment/how-to-create-payment-provider.md index da374726c3..c204a1690d 100644 --- a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md +++ b/docs/content/advanced/backend/payment/how-to-create-payment-provider.md @@ -50,54 +50,64 @@ The first step to create a payment provider is to create a JavaScript or TypeScr For example, create the file `src/services/my-payment.ts` with the following content: - - ```ts title=src/services/my-payment.ts import { - AbstractPaymentService, - Cart, Data, Payment, PaymentSession, - PaymentSessionStatus, TransactionBaseService, -} from "@medusajs/medusa" + AbstractPaymentService, PaymentContext, Data, + Payment, PaymentSession, PaymentSessionStatus, + PaymentSessionData, Cart, PaymentData, + PaymentSessionResponse } from "@medusajs/medusa" + import { EntityManager } from "typeorm" -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { protected manager_: EntityManager - protected transactionManager_: EntityManager + protected transactionManager_: EntityManager | undefined - getPaymentData(paymentSession: PaymentSession): Promise { + async getPaymentData(paymentSession: PaymentSession): Promise { throw new Error("Method not implemented.") } - updatePaymentData(paymentSessionData: Data, data: Data): Promise { + async updatePaymentData( + paymentSessionData: PaymentSessionData, + data: Data + ): Promise { throw new Error("Method not implemented.") } - createPayment(cart: Cart): Promise { + async createPayment( + context: Cart & PaymentContext + ): Promise { throw new Error("Method not implemented.") } - retrievePayment(paymentData: Data): Promise { + async retrievePayment(paymentData: Data): Promise { throw new Error("Method not implemented.") } - updatePayment(paymentSessionData: Data, cart: Cart): Promise { + async updatePayment( + paymentSessionData: PaymentSessionData, + cart: Cart + ): Promise { throw new Error("Method not implemented.") } - authorizePayment( + async authorizePayment( paymentSession: PaymentSession, context: Data - ): Promise<{ data: Data; status: PaymentSessionStatus; }> { + ): Promise<{ data: PaymentSessionData; status: PaymentSessionStatus }> { throw new Error("Method not implemented.") } - capturePayment(payment: Payment): Promise { + async capturePayment(payment: Payment): Promise { throw new Error("Method not implemented.") } - refundPayment(payment: Payment, refundAmount: number): Promise { + async refundPayment( + payment: Payment, + refundAmount: number + ): Promise { throw new Error("Method not implemented.") } - cancelPayment(payment: Payment): Promise { + async cancelPayment(payment: Payment): Promise { throw new Error("Method not implemented.") } - deletePayment(paymentSession: PaymentSession): Promise { + async deletePayment(paymentSession: PaymentSession): Promise { throw new Error("Method not implemented.") } - getStatus(data: Data): Promise { + async getStatus(data: Data): Promise { throw new Error("Method not implemented.") } @@ -132,13 +142,11 @@ You can also use the constructor to initialize your integration with the third-p Additionally, if you’re creating your Payment Provider as an external plugin to be installed on any Medusa server and you want to access the options added for the plugin, you can access it in the constructor. The options are passed as a second parameter: - - ```ts -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... - constructor({ productService }, options) { - super() + constructor(container, options) { + super(container) // you can access options here } // ... @@ -147,26 +155,62 @@ class MyPaymentService extends AbstractPaymentService { ### createPayment -This method is called during checkout when [Payment Sessions are initialized](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartPaymentSessions) to present payment options to the customer. It is used to allow you to make any necessary calls to the third-party provider to initialize the payment. For example, in Stripe this method is used to initialize a Payment Intent for the customer. +This method is called during checkout when [Payment Sessions are initialized](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartPaymentSessions) to present payment options to the customer. It is used to allow you to make any necessary calls to the third-party provider to initialize the payment. -The method receives the cart as an object for its first parameter. It holds all the necessary information you need to know about the cart and the customer that owns this cart. +For example, in Stripe this method is used to initialize a Payment Intent for the customer. -This method must return an object that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](./overview.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point. - -An example of a minimal implementation of `createPayment` that does not interact with any third-party providers: - - +The method receives a context object as a first parameter. This object is of type `PaymentContext` and has the following properties: ```ts -import { Cart, Data } from "@medusajs/medusa" -// ... +type PaymentContext = { + cart: { + context: Record + id: string + email: string + shipping_address: Address | null + shipping_methods: ShippingMethod[] + } + currency_code: string + amount: number + resource_id?: string + customer?: Customer +} +``` -class MyPaymentService extends AbstractPaymentService { +:::note + +Before v1.7.2, the first parameter was of type `Cart`. This method remains backwards compatible, but will be changed in the future. So, it's recommended to change the type of the first parameter to `PaymentContext`. + +::: + +This method must return an object of type `PaymentSessionResponse`. It should have the following properties: + +```ts +type PaymentSessionResponse = { + update_requests: { customer_metadata: Record } + session_data: Record +} +``` + +Where: + +- `session_data` is the data that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](./overview.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point. +- `update_requests` is an object that can be used to pass data from the payment provider plugin to the core to update internal resources. Currently, it only has one attribute `customer_metadata` which allows updating the `metadata` field of the customer. + +An example of a minimal implementation of `createPayment`: + +```ts +import { PaymentContext, PaymentSessionResponse } from "@medusajs/medusa" + +class MyPaymentService extends AbstractPaymentService { // ... - async createPayment(cart: Cart): Promise { + async createPayment( + context: Cart & PaymentContext + ): Promise { + // prepare data return { - id: "test-payment", - status: "pending", + session_data, + update_requests, } } } @@ -182,13 +226,11 @@ This method must return an object containing the data from the third-party provi An example of a minimal implementation of `retrievePayment` where you don’t need to interact with the third-party provider: - - ```ts import { Data } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async retrievePayment(paymentData: Data): Promise { return {} @@ -214,13 +256,11 @@ This method returns a string that represents the status. The status must be one An example of a minimal implementation of `getStatus` where you don’t need to interact with the third-party provider: - - ```ts import { Data, PaymentSessionStatus } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async getStatus(data: Data): Promise { return PaymentSessionStatus.AUTHORIZED @@ -244,24 +284,68 @@ A line item refers to a product in the cart. ::: -It accepts the `data` field of the Payment Session as the first parameter and the cart as an object for the second parameter. +It accepts the `data` field of the Payment Session as the first parameter and a context object as a second parameter. This object is of type `PaymentContext` and has the following properties: + +```ts +type PaymentContext = { + cart: { + context: Record + id: string + email: string + shipping_address: Address | null + shipping_methods: ShippingMethod[] + } + currency_code: string + amount: number + resource_id?: string + customer?: Customer +} +``` + +:::note + +Before v1.7.2, the second parameter was of type `Cart`. This method remains backwards compatible, but will be changed in the future. So, it's recommended to change the type of the first parameter to `PaymentContext`. + +::: You can utilize this method to interact with the third-party provider and update any details regarding the payment if necessary. -This method must return an object that will be stored in the `data` field of the Payment Session. - -An example of a minimal implementation of `updatePayment` that does not need to make any updates on the third-party provider or the `data` field of the Payment Session: - - +This method must return an object of type `PaymentSessionResponse`. It should have the following properties: ```ts -import { Cart, Data } from "@medusajs/medusa" +type PaymentSessionResponse = { + update_requests: { customer_metadata: Record } + session_data: Record +} +``` + +Where: + +- `session_data` is the data that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](./overview.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point. +- `update_requests` is an object that can be used to request from the Medusa core to update internal resources. Currently, it only has one attribute `customer_metadata` which allows updating the `metadata` field of the customer. + +An example of a minimal implementation of `updatePayment`: + +```ts +import { + PaymentSessionData, + Cart, + PaymentContext, + PaymentSessionResponse, +} from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... - async updatePayment(paymentSessionData: Data, cart: Cart): Promise { - return paymentSessionData + async updatePayment( + paymentSessionData: PaymentSessionData, + cart: Cart + ): Promise { + // prepare data + return { + session_data, + update_requests, + } } } ``` @@ -278,18 +362,16 @@ This method must return an object that will be stored in the `data` field of the An example of a minimal implementation of `updatePaymentData` that returns the `updatedData` passed in the body of the request as-is to update the `data` field of the Payment Session. - - ```ts -import { Data } from "@medusajs/medusa" +import { Data, PaymentSessionData } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async updatePaymentData( - paymentSessionData: Data, - updatedData: Data - ): Promise { + paymentSessionData: PaymentSessionData, + data: Data + ): Promise { return updatedData } } @@ -310,13 +392,11 @@ You can use this method to interact with the third-party provider to delete data An example of a minimal implementation of `deletePayment` where no interaction with a third-party provider is required: - - ```ts import { PaymentSession } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async deletePayment(paymentSession: PaymentSession): Promise { return @@ -353,22 +433,21 @@ You can utilize this method to interact with the third-party provider and perfor An example of a minimal implementation of `authorizePayment` that doesn’t need to interact with any third-party provider: - - ```ts import { Data, PaymentSession, PaymentSessionStatus, + PaymentSessionData, } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async authorizePayment( paymentSession: PaymentSession, context: Data - ): Promise<{ data: Data; status: PaymentSessionStatus; }> { + ): Promise<{ data: PaymentSessionData; status: PaymentSessionStatus }> { return { status: PaymentSessionStatus.AUTHORIZED, data: { @@ -389,13 +468,11 @@ This method must return an object to be stored in the `data` field of the Paymen An example of a minimal implementation of `getPaymentData`: - - ```ts import { Data, PaymentSession } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async getPaymentData(paymentSession: PaymentSession): Promise { return paymentSession.data @@ -417,13 +494,11 @@ This method must return an object that will be stored in the `data` field of the An example of a minimal implementation of `capturePayment` that doesn’t need to interact with a third-party provider: - - ```ts import { Data, Payment } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async capturePayment(payment: Payment): Promise { return { @@ -447,13 +522,11 @@ This method must return an object that is stored in the `data` field of the Paym An example of a minimal implementation of `refundPayment` that doesn’t need to interact with a third-party provider: - - ```ts import { Data, Payment } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async refundPayment( payment: Payment, @@ -483,13 +556,11 @@ This method must return an object that is stored in the `data` field of the Paym An example of a minimal implementation of `cancelPayment` that doesn’t need to interact with a third-party provider: - - ```ts import { Data, Payment } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... async cancelPayment(payment: Payment): Promise { return { @@ -521,13 +592,11 @@ If you’re using Medusa’s [Next.js](../../../starters/nextjs-medusa-starter.m An example of the implementation of `retrieveSavedMethods` taken from Stripe’s Payment Provider: - - ```ts import { Customer, Data } from "@medusajs/medusa" // ... -class MyPaymentService extends AbstractPaymentService { +class MyPaymentService extends AbstractPaymentService { // ... /** * Fetches a customers saved payment methods if registered in Stripe. diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-1.md b/docs/content/advanced/backend/upgrade-guides/1-7-1.md index 1a1f2d617c..3ac0f87a97 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-7-1.md +++ b/docs/content/advanced/backend/upgrade-guides/1-7-1.md @@ -76,20 +76,20 @@ Although this change is currently backwards compatible, it is recommended to cha ```ts -import { PaymentContext, PaymentSessionResponse } from "@medusajs/medusa" +import { Cart, PaymentSessionData, PaymentContext, PaymentSessionResponse } from "@medusajs/medusa" // ... class MyPaymentService extends AbstractPaymentService { // ... async createPayment( - context: PaymentContext + context: Cart & PaymentContext ): Promise { // ... } async updatePayment( paymentSessionData: PaymentSessionData, - context: PaymentContext + context: Cart & PaymentContext ): Promise { // ... }