@etohq/utils 1.4.0 → 1.5.0

package/dist/payment/abstract-payment-provider.d.ts

@@ -1,4 +1,4 @@
-import { CreatePaymentProviderSession, IPaymentProvider, PaymentProviderError, PaymentProviderSessionResponse, PaymentSessionStatus, ProviderWebhookPayload, UpdatePaymentProviderSession, WebhookActionResult } from "@etohq/types";
+import { IPaymentProvider, ProviderWebhookPayload, WebhookActionResult, CapturePaymentInput, CapturePaymentOutput, AuthorizePaymentInput, AuthorizePaymentOutput, CancelPaymentInput, CancelPaymentOutput, InitiatePaymentInput, InitiatePaymentOutput, DeletePaymentInput, DeletePaymentOutput, GetPaymentStatusInput, GetPaymentStatusOutput, RefundPaymentInput, RefundPaymentOutput, RetrievePaymentInput, RetrievePaymentOutput, UpdatePaymentInput, UpdatePaymentOutput } from "@etohq/types";
 export declare abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>> implements IPaymentProvider {
     /**
      * @ignore
@@ -10,11 +10,12 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
     protected readonly container: Record<string, unknown>;
     /**
      * This method validates the options of the provider set in `eto-config.ts`.
-     * Implementing this method is optional. It's useful if your provider requires custom validation.
+     * Implementing this method is optional, but it's useful to ensure that the required
+     * options are passed to the provider, or if you have any custom validation logic.
      *
      * If the options aren't valid, throw an error.
      *
-     * @param options - The provider's options.
+     * @param options - The provider's options passed in `eto-config.ts`.
      *
      * @example
      * class MyPaymentProviderService extends AbstractPaymentProvider<Options> {
@@ -30,16 +31,18 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      */
     static validateOptions(options: Record<any, any>): void | never;
     /**
-     * The constructor allows you to access resources from the [module's container](https://docs.etohq.com/learn/fundamentals/commerce-modules/container)
+     * The constructor allows you to access resources from the [module's container](https://docs.etohq.com/learn/fundamentals/modules/container)
      * using the first parameter, and the module's options using the second parameter.
      *
+     * If you're creating a client or establishing a connection with a third-party service, do it in the constructor.
+     *
      * :::note
      *
      * A module's options are passed when you register it in the Eto application.
      *
      * :::
      *
-     * @param {Record<string, unknown>} cradle - The module's container cradle used to resolve resources.
+     * @param {Record<string, unknown>} cradle - The module's container used to resolve resources.
      * @param {Record<string, unknown>} config - The options passed to the Payment Module provider.
      * @typeParam TConfig - The type of the provider's options passed as a second parameter.
      *
@@ -111,75 +114,90 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      */
     getIdentifier(): string;
     /**
-     * This method is used to capture a payment. The payment is captured in one of the following scenarios:
+     * This method captures a payment using the third-party provider. In this method, use the third-party provider to capture the payment.
      *
-     * - The {@link authorizePayment} method returns the status `captured`, which automatically executed this method after authorization.
-     * - The merchant requests to capture the payment after its associated payment session was authorized.
-     * - A webhook event occurred that instructs the payment provider to capture the payment session. Learn more about handing webhook events in [this guide](https://docs.etohq.com/resources/commerce-modules/payment/webhook-events).
+     * When an order is placed, the payment is authorized using the {@link authorizePayment} method. Then, the admin
+     * user can capture the payment, which triggers this method.
      *
-     * In this method, use the third-party provider to capture the payment.
+     * ![Diagram showcasing capture payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747307414/Eto%20Resources/Klarna_Payment_Graphic_2025_1_lii7bw.jpg)
      *
-     * @param paymentData - The `data` property of the payment. Make sure to store in it
-     * any helpful identification for your third-party integration.
-     * @returns The new data to store in the payment's `data` property, or an error object.
+     * This method can also be triggered by a webhook event if the {@link getWebhookActionAndData} method returns the action `captured`.
+     *
+     * #### Understanding `data` property
+     *
+     * The `data` property of the input parameter contains data that was previously stored in the Payment record's `data` property, which was
+     * returned by the {@link authorizePayment} method.
+     *
+     * The `data` property returned by this method is then stored in the `Payment` record. You can store data relevant to later refund or process the payment.
+     * For example, you can store the ID of the payment in the third-party provider to reference it later.
+     *
+     * ![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747309870/Eto%20Resources/capture-data_acgdhf.jpg)
+     *
+     * @param input - The input to capture the payment. The `data` field should contain the data from the payment provider. when the payment was created.
+     * @returns The new data to store in the payment's `data` property. Throws in case of an error.
      *
      * @example
      * // other imports...
      * import {
-     *   PaymentProviderError,
-     *   PaymentProviderSessionResponse,
+     *   CapturePaymentInput,
+     *   CapturePaymentOutput,
      * } from "@etohq/framework/types"
      *
      * class MyPaymentProviderService extends AbstractPaymentProvider<
      *   Options
      * > {
      *   async capturePayment(
-     *     paymentData: Record<string, unknown>
-     *   ): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]> {
-     *     const externalId = paymentData.id
+     *     input: CapturePaymentInput
+     *   ): Promise<CapturePaymentOutput> {
+     *     const externalId = input.data?.id
      *
-     *     try {
      *       // assuming you have a client that captures the payment
-     *       const newData = await this.client.capturePayment(externalId)
-     *
-     *       return {
+     *     const newData = await this.client.capturePayment(externalId)
+     *     return {
+     *       data: {
      *         ...newData,
-     *         id: externalId
-     *       }
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
+     *         id: externalId,
      *       }
      *     }
      *   }
-     *
      *   // ...
      * }
      */
-    abstract capturePayment(paymentData: Record<string, unknown>): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]>;
+    abstract capturePayment(input: CapturePaymentInput): Promise<CapturePaymentOutput>;
     /**
-     * This method authorizes a payment session. When authorized successfully, a payment is created by the Payment
-     * Module which can be later captured using the {@link capturePayment} method.
+     * This method authorizes a payment session using the third-party payment provider.
      *
-     * Refer to [this guide](https://docs.etohq.com/resources/commerce-modules/payment/payment-flow#3-authorize-payment-session)
-     * to learn more about how this fits into the payment flow and how to handle required actions.
+     * During checkout, the customer may need to perform actions required by the payment provider,
+     * such as entering their card details or confirming the payment. Once that is done,
+     * the customer can place their order.
      *
-     * To automatically capture the payment after authorization, return the status `captured`.
+     * During cart-completion before placing the order, this method is used to authorize the cart's payment session with the
+     * third-party payment provider. The payment can later be captured
+     * using the {@link capturePayment} method.
      *
-     * @param paymentSessionData - The `data` property of the payment session. Make sure to store in it
-     * any helpful identification for your third-party integration.
-     * @param context - The context in which the payment is being authorized. For example, in checkout,
-     * the context has a `cart_id` property indicating the ID of the associated cart.
-     * @returns Either an object of the new data to store in the created payment's `data` property and the
-     * payment's status, or an error object. Make sure to set in `data` anything useful to later retrieve the session.
+     * ![Diagram showcasing authorize payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747307795/Eto%20Resources/authorize-payment_qzpy6e.jpg)
+     *
+     * When authorized successfully, a `Payment` is created by the Payment
+     * Module, and it's associated with the order.
+     *
+     * #### Understanding `data` property
+     *
+     * The `data` property of the method's parameter contains the `PaymentSession` record's `data` property, which was
+     * returned by the {@link initiatePayment} method.
+     *
+     * The `data` property returned by this method is then stored in the created `Payment` record. You can store data relevant to later capture or process the payment.
+     * For example, you can store the ID of the payment in the third-party provider to reference it later.
+     *
+     * ![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747309278/Eto%20Resources/authorize-data_erjg7r.jpg)
+     *
+     * @param input - The input to authorize the payment. The `data` field should contain the data from the payment provider. when the payment was created.
+     * @returns The status of the authorization, along with the `data` field about the payment. Throws in case of an error.
      *
      * @example
      * // other imports...
      * import {
-     *   PaymentProviderError,
-     *   PaymentProviderSessionResponse,
+     *   AuthorizePaymentInput,
+     *   AuthorizePaymentOutput,
      *   PaymentSessionStatus
      * } from "@etohq/framework/types"
      *
@@ -188,55 +206,39 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async authorizePayment(
-     *     paymentSessionData: Record<string, unknown>,
-     *     context: Record<string, unknown>
-     *   ): Promise<
-     *     PaymentProviderError | {
-     *       status: PaymentSessionStatus
-     *       data: PaymentProviderSessionResponse["data"]
-     *     }
-     *   > {
-     *     const externalId = paymentSessionData.id
+     *     input: AuthorizePaymentInput
+     *   ): Promise<AuthorizePaymentOutput> {
+     *     const externalId = input.data?.id
      *
-     *     try {
-     *       // assuming you have a client that authorizes the payment
-     *       const paymentData = await this.client.authorizePayment(externalId)
+     *     // assuming you have a client that authorizes the payment
+     *     const paymentData = await this.client.authorizePayment(externalId)
      *
-     *       return {
-     *         data: {
-     *           ...paymentData,
-     *           id: externalId
-     *         },
-     *         status: "authorized"
-     *       }
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
-     *       }
+     *     return {
+     *       data: paymentData,
+     *       status: "authorized"
      *     }
      *   }
      *
      *   // ...
      * }
      */
-    abstract authorizePayment(paymentSessionData: Record<string, unknown>, context: Record<string, unknown>): Promise<PaymentProviderError | {
-        /**
-         * The new status of the payment.
-         */
-        status: PaymentSessionStatus;
-        /**
-         * The data to store in the created payment's `data` property.
-         */
-        data: PaymentProviderSessionResponse["data"];
-    }>;
+    abstract authorizePayment(input: AuthorizePaymentInput): Promise<AuthorizePaymentOutput>;
     /**
-     * This method cancels a payment.
+     * This method cancels a payment in the third-party payment provider. It's used when
+     * the admin user cancels an order. The order can only be canceled if the payment
+     * is not captured yet.
+     *
+     * #### Understanding `data` property
+     *
+     * The `data` property of the method's parameter contains the `Payment` record's `data` property, which was
+     * returned by the {@link authorizePayment} method.
+     *
+     * The `data` property returned by this method is then stored in the `Payment` record. You can store data relevant for any further processing of the payment.
      *
-     * @param paymentData - The `data` property of the payment. Make sure to store in it
-     * any helpful identification for your third-party integration.
-     * @returns An error object if an error occurs, or the data received from the integration.
+     * ![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747310189/Eto%20Resources/cancel-data_gzcgbc.jpg)
+     *
+     * @param input - The input to cancel the payment. The `data` field should contain the data from the payment provider. when the payment was created.
+     * @returns The new data to store in the payment's `data` property, if any. Throws in case of an error.
      *
      * @example
      * // other imports...
@@ -250,39 +252,51 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async cancelPayment(
-     *     paymentData: Record<string, unknown>
-     *   ): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]> {
-     *     const externalId = paymentData.id
+     *     input: CancelPaymentInput
+     *   ): Promise<CancelPaymentOutput> {
+     *     const externalId = input.data?.id
      *
-     *     try {
-     *       // assuming you have a client that cancels the payment
-     *       const paymentData = await this.client.cancelPayment(externalId)
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
-     *       }
-     *     }
+     *     // assuming you have a client that cancels the payment
+     *     const paymentData = await this.client.cancelPayment(externalId)
+     *     return { data: paymentData }
      *   }
      *
      *   // ...
      * }
      */
-    abstract cancelPayment(paymentData: Record<string, unknown>): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]>;
+    abstract cancelPayment(input: CancelPaymentInput): Promise<CancelPaymentOutput>;
     /**
-     * This method is used when a payment session is created. It can be used to initiate the payment
-     * in the third-party session, before authorizing or capturing the payment later.
+     * This method initializes a payment session with the third-party payment provider.
+     *
+     * When a customer chooses a payment method during checkout, this method is triggered to
+     * perform any initialization action with the third-party provider, such as creating a payment session.
+     *
+     * ![Diagram showcasing initiate payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747310624/Eto%20Resources/initiate-payment_dpoa2g.jpg)
      *
-     * @param context - The details of the payment session and its context.
-     * @returns An object whose `data` property is set in the created payment session, or an error
-     * object. Make sure to set in `data` anything useful to later retrieve the session.
+     * #### Understanding `data` property
+     *
+     * The `data` property returned by this method will be stored in the created `PaymentSession` record. You can store data relevant to later authorize or process the payment.
+     * For example, you can store the ID of the payment session in the third-party provider to reference it later.
+     *
+     * The `data` property is also available to storefronts, allowing you to store data necessary for the storefront to integrate
+     * the payment provider in the checkout flow. For example, you can store the client token to use with the payment provider's SDK.
+     *
+     * :::note
+     *
+     * This also means you shouldn't store sensitive data and tokens in the `data` property, as it's publicly accessible.
+     *
+     * :::
+     *
+     * ![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747310699/Eto%20Resources/initiate-data_ikc05t.jpg)
+     *
+     * @param input - The input to create the payment session.
+     * @returns The new data to store in the payment's `data` property. Throws in case of an error.
      *
      * @example
      * // other imports...
      * import {
-     *   PaymentProviderError,
-     *   PaymentProviderSessionResponse,
+     *   InitiatePaymentInput,
+     *   InitiatePaymentOutput,
      * } from "@etohq/framework/types"
      *
      *
@@ -290,53 +304,55 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async initiatePayment(
-     *     context: CreatePaymentProviderSession
-     *   ): Promise<PaymentProviderError | PaymentProviderSessionResponse> {
+     *     input: InitiatePaymentInput
+     *   ): Promise<InitiatePaymentOutput> {
      *     const {
      *       amount,
      *       currency_code,
      *       context: customerDetails
-     *     } = context
+     *     } = input
      *
-     *     try {
-     *       // assuming you have a client that initializes the payment
-     *       const response = await this.client.init(
-     *         amount, currency_code, customerDetails
-     *       )
+     *     // assuming you have a client that initializes the payment
+     *     const response = await this.client.init(
+     *       amount, currency_code, customerDetails
+     *     )
      *
-     *       return {
-     *         ...response,
-     *         data: {
-     *           id: response.id
-     *         }
-     *       }
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
-     *       }
+     *     return {
+     *       id: response.id,
+     *       data: response,
      *     }
      *   }
      *
      *   // ...
      * }
      */
-    abstract initiatePayment(context: CreatePaymentProviderSession): Promise<PaymentProviderError | PaymentProviderSessionResponse>;
+    abstract initiatePayment(input: InitiatePaymentInput): Promise<InitiatePaymentOutput>;
     /**
-     * This method is used when a payment session is deleted, which can only happen if it isn't authorized, yet.
+     * This method deletes a payment session in the third-party payment provider.
+     *
+     * When a customer chooses a payment method during checkout, then chooses a different one,
+     * this method is triggered to delete the previous payment session.
+     *
+     * If your provider doesn't support deleting a payment session, you can just return an empty object or
+     * an object that contains the same received `data` property.
+     *
+     * ![Diagram showcasing delete payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747311084/Eto%20Resources/delete-payment_smxsiq.jpg)
      *
-     * Use this to delete or cancel the payment in the third-party service.
+     * #### Understanding `data` property
      *
-     * @param paymentSessionData - The `data` property of the payment session. Make sure to store in it
-     * any helpful identification for your third-party integration.
-     * @returns An error object or the response from the third-party service.
+     * The `data` property of the method's parameter contains the `PaymentSession` record's `data` property, which was
+     * returned by the {@link initiatePayment} method.
+     *
+     * ![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747311084/Eto%20Resources/delete-data_xg65ck.jpg)
+     *
+     * @param input - The input to delete the payment session. The `data` field should contain the data from the payment provider. when the payment was created.
+     * @returns The new data to store in the payment's `data` property, if any. Throws in case of an error.
      *
      * @example
      * // other imports...
      * import {
-     *   PaymentProviderError,
-     *   PaymentProviderSessionResponse,
+     *   DeletePaymentInput,
+     *   DeletePaymentOutput,
      * } from "@etohq/framework/types"
      *
      *
@@ -344,38 +360,32 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async deletePayment(
-     *     paymentSessionData: Record<string, unknown>
-     *   ): Promise<
-     *     PaymentProviderError | PaymentProviderSessionResponse["data"]
-     *   > {
-     *     const externalId = paymentSessionData.id
-     *
-     *     try {
-     *       // assuming you have a client that cancels the payment
-     *       await this.client.cancelPayment(externalId)
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
-     *       }
+     *     input: DeletePaymentInput
+     *   ): Promise<DeletePaymentOutput> {
+     *     const externalId = input.data?.id
+     *
+     *     // assuming you have a client that cancels the payment
+     *     await this.client.cancelPayment(externalId)
+     *     return {
+     *       data: input.data
      *     }
      *   }
      *
      *   // ...
      * }
      */
-    abstract deletePayment(paymentSessionData: Record<string, unknown>): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]>;
+    abstract deletePayment(input: DeletePaymentInput): Promise<DeletePaymentOutput>;
     /**
      * This method gets the status of a payment session based on the status in the third-party integration.
      *
-     * @param paymentSessionData - The `data` property of the payment session. Make sure to store in it
-     * any helpful identification for your third-party integration.
-     * @returns The payment session's status.
+     * @param input - The input to get the payment status. The `data` field should contain the data from the payment provider. when the payment was created.
+     * @returns The payment session's status. It can also return additional `data` from the payment provider.
      *
      * @example
      * // other imports...
      * import {
+     *   GetPaymentStatusInput,
+     *   GetPaymentStatusOutput,
      *   PaymentSessionStatus
      * } from "@etohq/framework/types"
      *
@@ -384,46 +394,58 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async getPaymentStatus(
-     *     paymentSessionData: Record<string, unknown>
-     *   ): Promise<PaymentSessionStatus> {
-     *     const externalId = paymentSessionData.id
+     *     input: GetPaymentStatusInput
+     *   ): Promise<GetPaymentStatusOutput> {
+     *     const externalId = input.data?.id
      *
-     *     try {
-     *       // assuming you have a client that retrieves the payment status
-     *       const status = await this.client.getStatus(externalId)
+     *     // assuming you have a client that retrieves the payment status
+     *     const status = await this.client.getStatus(externalId)
      *
-     *       switch (status) {
-     *         case "requires_capture":
-     *           return "authorized"
+     *     switch (status) {
+     *       case "requires_capture":
+     *           return {status: "authorized"}
      *         case "success":
-     *           return "captured"
+     *           return {status: "captured"}
      *         case "canceled":
-     *           return "canceled"
+     *           return {status: "canceled"}
      *         default:
-     *           return "pending"
-     *       }
-     *     } catch (e) {
-     *       return "error"
-     *     }
+     *           return {status: "pending"}
+     *      }
      *   }
      *
      *   // ...
      * }
      */
-    abstract getPaymentStatus(paymentSessionData: Record<string, unknown>): Promise<PaymentSessionStatus>;
+    abstract getPaymentStatus(input: GetPaymentStatusInput): Promise<GetPaymentStatusOutput>;
     /**
-     * This method refunds an amount of a payment previously captured.
+     * This method refunds an amount using the third-party payment provider. This method
+     * is triggered when the admin user refunds a payment of an order.
+     *
+     * #### Understanding `data` property
+     *
+     * The `data` property of the method's parameter contains the `Payment` record's `data` property, which was
+     * returned by the {@link capturePayment} or {@link refundPayment} method.
+     *
+     * The `data` property returned by this method is then stored in the `Payment` record. You can store data relevant to later refund or process the payment.
+     * For example, you can store the ID of the payment in the third-party provider to reference it later.
      *
-     * @param paymentData - The `data` property of the payment. Make sure to store in it
-     * any helpful identification for your third-party integration.
-     * @param refundAmount The amount to refund.
+     * :::note
+     *
+     * A payment may be refunded multiple times with different amounts. In this case, the `data` property
+     * of the input parameter contains the data from the last refund.
+     *
+     * :::
+     *
+     * ![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747311296/Eto%20Resources/refund-data_plcjl0.jpg)
+     *
+     * @param input - The input to refund the payment. The `data` field should contain the data from the payment provider. when the payment was created.
      * @returns The new data to store in the payment's `data` property, or an error object.
      *
      * @example
      * // other imports...
      * import {
-     *   PaymentProviderError,
-     *   PaymentProviderSessionResponse,
+     *   RefundPaymentInput,
+     *   RefundPaymentOutput,
      * } from "@etohq/framework/types"
      *
      *
@@ -431,49 +453,35 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async refundPayment(
-     *     paymentData: Record<string, unknown>,
-     *     refundAmount: number
-     *   ): Promise<
-     *     PaymentProviderError | PaymentProviderSessionResponse["data"]
-     *   > {
-     *     const externalId = paymentData.id
+     *     input: RefundPaymentInput
+     *   ): Promise<RefundPaymentOutput> {
+     *     const externalId = input.data?.id
      *
-     *     try {
-     *       // assuming you have a client that refunds the payment
-     *       const newData = await this.client.refund(
+     *     // assuming you have a client that refunds the payment
+     *     const newData = await this.client.refund(
      *         externalId,
-     *         refundAmount
+     *         input.amount
      *       )
      *
-     *       return {
-     *         ...newData,
-     *         id: externalId
-     *       }
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
-     *       }
+     *     return {
+     *       data: input.data,
      *     }
      *   }
-     *
      *   // ...
      * }
      */
-    abstract refundPayment(paymentData: Record<string, unknown>, refundAmount: number): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]>;
+    abstract refundPayment(input: RefundPaymentInput): Promise<RefundPaymentOutput>;
     /**
-     * Retrieves the payment's data from the third-party service.
+     * This method retrieves the payment's data from the third-party payment provider.
      *
-     * @param paymentSessionData - The `data` property of the payment. Make sure to store in it
-     * any helpful identification for your third-party integration.
-     * @returns An object to be stored in the payment's `data` property, or an error object.
+     * @param input - The input to retrieve the payment. The `data` field should contain the data from the payment provider when the payment was created.
+     * @returns The payment's data as found in the the payment provider.
      *
      * @example
      * // other imports...
      * import {
-     *   PaymentProviderError,
-     *   PaymentProviderSessionResponse,
+     *   RetrievePaymentInput,
+     *   RetrievePaymentOutput,
      * } from "@etohq/framework/types"
      *
      *
@@ -481,41 +489,28 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async retrievePayment(
-     *     paymentSessionData: Record<string, unknown>
-     *   ): Promise<
-     *     PaymentProviderError | PaymentProviderSessionResponse["data"]
-     *   > {
-     *     const externalId = paymentSessionData.id
+     *     input: RetrievePaymentInput
+     *   ): Promise<RetrievePaymentOutput> {
+     *     const externalId = input.data?.id
      *
-     *     try {
-     *       // assuming you have a client that retrieves the payment
-     *       return await this.client.retrieve(externalId)
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
-     *       }
-     *     }
+     *     // assuming you have a client that retrieves the payment
+     *     return await this.client.retrieve(externalId)
      *   }
-     *
      *   // ...
      * }
      */
-    abstract retrievePayment(paymentSessionData: Record<string, unknown>): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]>;
+    abstract retrievePayment(input: RetrievePaymentInput): Promise<RetrievePaymentOutput>;
     /**
-     * Update a payment in the third-party service that was previously initiated with the {@link initiatePayment} method.
+     * This method updates a payment in the third-party service that was previously initiated with the {@link initiatePayment} method.
      *
-     * @param context - The details of the payment session and its context.
-     * @returns An object whose `data` property is set in the updated payment session, or an error
-     * object. Make sure to set in `data` anything useful to later retrieve the session.
+     * @param input - The input to update the payment. The `data` field should contain the data from the payment provider. when the payment was created.
+     * @returns The new data to store in the payment's `data` property. Throws in case of an error.
      *
      * @example
      * // other imports...
      * import {
-     *   UpdatePaymentProviderSession,
-     *   PaymentProviderError,
-     *   PaymentProviderSessionResponse,
+     *   UpdatePaymentInput,
+     *   UpdatePaymentOutput,
      * } from "@etohq/framework/types"
      *
      *
@@ -523,55 +518,44 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *   Options
      * > {
      *   async updatePayment(
-     *     context: UpdatePaymentProviderSession
-     *   ): Promise<PaymentProviderError | PaymentProviderSessionResponse> {
-     *     const {
-     *       amount,
-     *       currency_code,
-     *       context: customerDetails,
-     *       data
-     *     } = context
-     *     const externalId = data.id
+     *     input: UpdatePaymentInput
+     *   ): Promise<UpdatePaymentOutput> {
+     *     const { amount, currency_code, context } = input
+     *     const externalId = input.data?.id
+     *
+     *     // Validate context.customer
+     *     if (!context || !context.customer) {
+     *       throw new Error("Context must include a valid customer.");
+     *     }
      *
-     *     try {
-     *       // assuming you have a client that updates the payment
-     *       const response = await this.client.update(
-     *         externalId,
+     *     // assuming you have a client that updates the payment
+     *     const response = await this.client.update(
+     *       externalId,
      *         {
      *           amount,
      *           currency_code,
-     *           customerDetails
+     *           customer: context.customer
      *         }
      *       )
      *
-     *       return {
-     *         ...response,
-     *         data: {
-     *           id: response.id
-     *         }
-     *       }
-     *     } catch (e) {
-     *       return {
-     *         error: e,
-     *         code: "unknown",
-     *         detail: e
-     *       }
-     *     }
+     *     return response
      *   }
      *
      *   // ...
      * }
      */
-    abstract updatePayment(context: UpdatePaymentProviderSession): Promise<PaymentProviderError | PaymentProviderSessionResponse>;
+    abstract updatePayment(input: UpdatePaymentInput): Promise<UpdatePaymentOutput>;
     /**
-     * This method is executed when a webhook event is received from the third-party payment provider. Use it
-     * to process the action of the payment provider.
+     * This method is executed when a webhook event is received from the third-party payment provider. Eto uses
+     * the data returned by this method to perform actions in the Eto application, such as completing the associated cart
+     * if the payment was authorized successfully.
      *
-     * Learn more in [this documentation](https://docs.etohq.com/resources/commerce-modules/payment/webhook-events)
+     * Learn more in the [Webhook Events](https://docs.etohq.com/resources/commerce-modules/payment/webhook-events) documentation.
      *
      * @param data - The webhook event's data
      * @returns The webhook result. If the `action`'s value is `captured`, the payment is captured within Eto as well.
-     * If the `action`'s value is `authorized`, the associated payment session is authorized within Eto.
+     * If the `action`'s value is `authorized`, the associated payment session is authorized within Eto and the associated cart
+     * will be completed to create an order.
      *
      * @example
      * // other imports...
@@ -602,6 +586,8 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *           return {
      *             action: "authorized",
      *             data: {
+     *               // assuming the session_id is stored in the metadata of the payment
+     *               // in the third-party provider
      *               session_id: (data.metadata as Record<string, any>).session_id,
      *               amount: new BigNumber(data.amount as number)
      *             }
@@ -610,19 +596,27 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      *           return {
      *             action: "captured",
      *             data: {
+     *               // assuming the session_id is stored in the metadata of the payment
+     *               // in the third-party provider
      *               session_id: (data.metadata as Record<string, any>).session_id,
      *               amount: new BigNumber(data.amount as number)
      *             }
      *           }
      *         default:
      *           return {
-     *             action: "not_supported"
+     *             action: "not_supported",
+     *             data: {
+     *               session_id: "",
+     *               amount: new BigNumber(0)
+     *             }
      *           }
      *       }
      *     } catch (e) {
      *       return {
      *         action: "failed",
      *         data: {
+     *           // assuming the session_id is stored in the metadata of the payment
+     *           // in the third-party provider
      *           session_id: (data.metadata as Record<string, any>).session_id,
      *           amount: new BigNumber(data.amount as number)
      *         }
@@ -635,8 +629,4 @@ export declare abstract class AbstractPaymentProvider<TConfig = Record<string, u
      */
     abstract getWebhookActionAndData(data: ProviderWebhookPayload["payload"]): Promise<WebhookActionResult>;
 }
-/**
- * @ignore
- */
-export declare function isPaymentProviderError(obj: any): obj is PaymentProviderError;
 //# sourceMappingURL=abstract-payment-provider.d.ts.map