Skip to main content
Skip to main content
You're viewing the documentation for v1, which isn't the latest Medusa version.Latest documentation

IPaymentModuleService

The main service interface for the Payment Module.

Methods​

createPaymentCollections​

**createPaymentCollections**(data, sharedContext?): Promise<[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)[]>

This method creates payment collections.

Example​

const paymentCollections =
  await paymentModuleService.createPaymentCollections([
    {
      region_id: "reg_123",
      currency_code: "usd",
      amount: 3000,
    },
    {
      region_id: "reg_321",
      currency_code: "eur",
      amount: 2000,
    },
  ])

Parameters​

dataCreatePaymentCollectionDTO[]Required
The payment collections to create.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO[]>Required
The created payment collections.

**createPaymentCollections**(data, sharedContext?): Promise&#60;[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)&#62;

This method creates a payment collection.

Example​

const paymentCollection =
  await paymentModuleService.createPaymentCollections({
    region_id: "reg_123",
    currency_code: "usd",
    amount: 3000,
  })

Parameters​

dataCreatePaymentCollectionDTORequired
The payment collection to create.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO>Required
The created payment collection.

retrievePaymentCollection​

This method retrieves a payment collection by its ID.

Example​

A simple example that retrieves a {type name} by its ID:

const paymentCollection =
  await paymentModuleService.retrievePaymentCollection(
    "pay_col_123"
  )

To specify relations that should be retrieved:

const paymentCollection =
  await paymentModuleService.retrievePaymentCollection(
    "pay_col_123",
    {
      relations: ["payment_sessions"],
    }
  )

Parameters​

paymentCollectionIdstringRequired
The payment collection's ID.
configFindConfig<PaymentCollectionDTO>
The configurations determining how the payment collection is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a payment collection.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO>Required
The retrieved payment collection.

listPaymentCollections​

This method retrieves a paginated list of payment collections based on optional filters and configuration.

Example​

To retrieve a list of payment collections using their IDs:

const paymentCollections =
  await paymentModuleService.listPaymentCollections({
    id: ["pay_col_123", "pay_col_321"],
  })

To specify relations that should be retrieved within the payment collection:

const paymentCollections =
  await paymentModuleService.listPaymentCollections(
    {
      id: ["pay_col_123", "pay_col_321"],
    },
    {
      relations: ["payment_sessions"],
    }
  )

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const paymentCollections =
  await paymentModuleService.listPaymentCollections(
    {
      id: ["pay_col_123", "pay_col_321"],
    },
    {
      relations: ["payment_sessions"],
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterablePaymentCollectionProps
The filters to apply on the retrieved payment collection.
configFindConfig<PaymentCollectionDTO>
The configurations determining how the payment collection is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a payment collection.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO[]>Required
The list of payment collections.

listAndCountPaymentCollections​

This method retrieves a paginated list of payment collections along with the total count of available payment collections satisfying the provided filters.

Example​

To retrieve a list of {type name} using their IDs:

const paymentCollections =
  await paymentModuleService.listAndCountPaymentCollections({
    id: ["pay_col_123", "pay_col_321"],
  })

To specify relations that should be retrieved within the {type name}:

const paymentCollections =
  await paymentModuleService.listAndCountPaymentCollections(
    {
      id: ["pay_col_123", "pay_col_321"],
    },
    {
      relations: ["payment_sessions"],
    }
  )

By default, only the first {default limit} records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const paymentCollections =
  await paymentModuleService.listAndCountPaymentCollections(
    {
      id: ["pay_col_123", "pay_col_321"],
    },
    {
      relations: ["payment_sessions"],
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterablePaymentCollectionProps
The filters to apply on the retrieved payment collection.
configFindConfig<PaymentCollectionDTO>
The configurations determining how the payment collection is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a payment collection.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<[PaymentCollectionDTO[], number]>Required
The list of payment collections along with their total count.

updatePaymentCollections​

**updatePaymentCollections**(paymentCollectionId, data, sharedContext?): Promise&#60;[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)&#62;

This method updates an existing payment collection.

Example​

const paymentCollection =
  await paymentModuleService.updatePaymentCollections(
    "pay_col_123",
    {
      amount: 3000,
    }
  )

Parameters​

paymentCollectionIdstringRequired
The payment collection's ID.
dataPaymentCollectionUpdatableFieldsRequired
The attributes to update in the payment collection.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO>Required
The updated payment collection.

**updatePaymentCollections**(selector, data, sharedContext?): Promise&#60;[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)[]&#62;

This method updates existing payment collections matching the specified filters.

Example​

const paymentCollections =
  await paymentModuleService.updatePaymentCollections(
    {
      id: ["pay_col_123", "pay_col_321"],
    },
    {
      currency_code: "usd",
    }
  )

Parameters​

selectorFilterablePaymentCollectionPropsRequired
The filters specifying which payment collections to update.
dataPaymentCollectionUpdatableFieldsRequired
The attributes to update in the payment collections.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO[]>Required
The updated payment collections.

upsertPaymentCollections​

**upsertPaymentCollections**(data, sharedContext?): Promise&#60;[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)[]&#62;

This method updates or creates payment collections if they don't exist.

Example​

const paymentCollections =
  await paymentModuleService.upsertPaymentCollections([
    {
      id: "pay_col_123",
      region_id: "reg_123",
    },
    {
      region_id: "reg_123",
      currency_code: "usd",
      amount: 3000,
    },
  ])

Parameters​

dataUpsertPaymentCollectionDTO[]Required
The attributes in the payment collections to be created or updated. If the object includes the id field, then the payment collection is updated. Otherise, it's created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO[]>Required
The created or updated payment collections.

**upsertPaymentCollections**(data, sharedContext?): Promise&#60;[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)&#62;

This method updates or creates a payment collection if it doesn't exist.

Example​

const paymentCollection =
  await paymentModuleService.upsertPaymentCollections({
    id: "pay_col_123",
    region_id: "reg_123",
  })

Parameters​

dataUpsertPaymentCollectionDTORequired
The attributes in the payment collection to be created or updated. If the id field is included, the payment collection is updated. Otherwise, it's created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO>Required
The created or updated payment collection.

deletePaymentCollections​

**deletePaymentCollections**(paymentCollectionId, sharedContext?): Promise&#60;void&#62;

This method deletes a payment collection by its ID.

Example​

await paymentModuleService.deletePaymentCollections([
  "pay_col_123",
  "pay_col_321",
])

Parameters​

paymentCollectionIdstring[]Required
The payment collection's ID.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the payment collection is deleted successfully.

**deletePaymentCollections**(paymentCollectionId, sharedContext?): Promise&#60;void&#62;

This method deletes a payment collection by its ID.

Example​

await paymentModuleService.deletePaymentCollections(
  "pay_col_123"
)

Parameters​

paymentCollectionIdstringRequired
The payment collection's ID.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the payment collection is deleted successfully.

completePaymentCollections​

**completePaymentCollections**(paymentCollectionId, sharedContext?): Promise&#60;[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)&#62;

This method marks a payment collection as completed by settings its completed_at field to the current date and time.

Example​

const paymentCollection =
  await paymentModuleService.completePaymentCollections(
    "pay_col_123"
  )

Parameters​

paymentCollectionIdstringRequired
The payment collection's ID.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO>Required
The payment collection's details.

**completePaymentCollections**(paymentCollectionId, sharedContext?): Promise&#60;[PaymentCollectionDTO](types.PaymentCollectionDTO.mdx)[]&#62;

This method marks payment collections as completed by settings their completed_at field to the current date and time.

Example​

const paymentCollection =
  await paymentModuleService.completePaymentCollections([
    "pay_col_123",
    "pay_col_321",
  ])

Parameters​

paymentCollectionIdstring[]Required
The payment collections' IDs.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentCollectionDTO[]>Required
The payment collections' details.

createPaymentSession​

This method creates a payment session in a payment collection.

Example​

const paymentSession =
  await paymentModuleService.createPaymentSession(
    "pay_col_1",
    {
      provider_id: "stripe",
      currency_code: "usd",
      amount: 3000,
      data: {},
    }
  )

Parameters​

paymentCollectionIdstringRequired
The ID of the payment collection to create the session for.
dataCreatePaymentSessionDTORequired
The details of the payment session.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentSessionDTO>Required
The payment collection's details.

updatePaymentSession​

This method updates a payment session.

Example​

const paymentSession =
  await paymentModuleService.updatePaymentSession({
    id: "payses_123",
    currency_code: "usd",
    amount: 3000,
    data: {},
  })

Parameters​

dataUpdatePaymentSessionDTORequired
The attributes to update in the payment session.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentSessionDTO>Required
The payment session's details.

deletePaymentSession​

This method deletes a payment session.

Example​

await paymentModuleService.deletePaymentSession("payses_123")

Parameters​

idstringRequired
The ID of the payment session.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves whent the payment session is deleted successfully.

authorizePaymentSession​

This method authorizes a payment session using its associated payment provider. This creates a payment that can later be captured.

Learn more about the payment flow in this guide

Example​

const payment =
  await paymentModuleService.authorizePaymentSession(
    "payses_123",
    {}
  )

Parameters​

idstringRequired
The payment session's ID.
contextRecord<string, unknown>Required
Context data to pass to the associated payment provider.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentDTO>Required
The created payment.

listPaymentSessions​

This method retrieves a paginated list of payment sessions based on optional filters and configuration.

Example​

To retrieve a list of payment sessions using their IDs:

const paymentSessions =
  await paymentModuleService.listPaymentSessions({
    id: ["payses_123", "payses_321"],
  })

To specify relations that should be retrieved within the payment session:

const paymentSessions =
  await paymentModuleService.listPaymentSessions(
    {
      id: ["payses_123", "payses_321"],
    },
    {
      relations: ["payment"],
    }
  )

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const paymentSessions =
  await paymentModuleService.listPaymentSessions(
    {
      id: ["payses_123", "payses_321"],
    },
    {
      relations: ["payment"],
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterablePaymentSessionProps
The filters to apply on the retrieved payment sessions.
configFindConfig<PaymentSessionDTO>
The configurations determining how the payment session is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a payment session.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentSessionDTO[]>Required
The list of payment sessions.

listPayments​

This method retrieves a paginated list of payments based on optional filters and configuration.

Example​

To retrieve a list of payments using their IDs:

const payments = await paymentModuleService.listPayments({
  id: ["pay_123", "pay_321"],
})

To specify relations that should be retrieved within the payment:

const payments = await paymentModuleService.listPayments(
  {
    id: ["pay_123", "pay_321"],
  },
  {
    relations: ["payment_session"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const payments = await paymentModuleService.listPayments(
  {
    id: ["pay_123", "pay_321"],
  },
  {
    relations: ["payment_session"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterablePaymentProps
The filters to apply on the retrieved payment.
configFindConfig<PaymentDTO>
The configurations determining how the payment is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a payment.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentDTO[]>Required
A list of payment.

updatePayment​

This method updates an existing payment.

Example​

const payment = await paymentModuleService.updatePayment({
  id: "pay_123",
  customer_id: "cus_123",
})

Parameters​

dataUpdatePaymentDTORequired
The attributes to update in the payment.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentDTO>Required
The updated payment.

capturePayment​

This method captures a payment using its associated payment provider.

Learn more about the payment flow in this guide

Example​

const payment = await paymentModuleService.capturePayment({
  payment_id: "pay_123",
})

Parameters​

dataCreateCaptureDTORequired
The payment capture to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentDTO>Required
The payment's details.

refundPayment​

This method refunds a payment using its associated payment provider. An amount can only be refunded if it has been captured first.

Example​

const payment = await paymentModuleService.refundPayment({
  payment_id: "pay_123",
  amount: 300,
})

Parameters​

dataCreateRefundDTORequired
The refund to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentDTO>Required
The payment's details.

cancelPayment​

This method cancels a payment.

Example​

const payment =
  await paymentModuleService.cancelPayment("pay_123")

Parameters​

paymentIdstringRequired
The payment's ID.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentDTO>Required
The payment's details.

listPaymentProviders​

This method retrieves a paginated list of payment providers based on optional filters and configuration.

Example​

To retrieve a list of payment providers using their IDs:

const paymentProviders =
  await paymentModuleService.listPaymentProviders({
    id: ["stripe", "system"],
  })

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const paymentProviders =
  await paymentModuleService.listPaymentProviders(
    {
      id: ["stripe", "system"],
    },
    {
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterablePaymentProviderProps
The filters to apply on the retrieved payment providers.
configFindConfig<PaymentProviderDTO>
The configurations determining how the payment provider is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a payment provider.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PaymentProviderDTO[]>Required
The list of payment providers.

listAndCountPaymentProviders​

Parameters​

Returns​

PromisePromise<[PaymentProviderDTO[], number]>Required

listCaptures​

This method retrieves a paginated list of captures based on optional filters and configuration.

Example​

To retrieve a list of captures using their IDs:

const captures = await paymentModuleService.listCaptures({
  id: ["capt_123", "capt_321"],
})

To specify relations that should be retrieved within the capture:

const captures = await paymentModuleService.listCaptures(
  {
    id: ["capt_123", "capt_321"],
  },
  {
    relations: ["payment"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const captures = await paymentModuleService.listCaptures(
  {
    id: ["capt_123", "capt_321"],
  },
  {
    relations: ["payment"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableCaptureProps
The filters to apply on the retrieved captures.
configFindConfig<CaptureDTO>
The configurations determining how the capture is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a capture.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<CaptureDTO[]>Required
The list of captures.

listRefunds​

This method retrieves a paginated list of refunds based on optional filters and configuration.

Example​

To retrieve a list of refunds using their IDs:

const refunds = await paymentModuleService.listRefunds({
  id: ["ref_123", "ref_321"],
})

To specify relations that should be retrieved within the refund:

const refunds = await paymentModuleService.listRefunds(
  {
    id: ["ref_123", "ref_321"],
  },
  {
    relations: ["payment"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const refunds = await paymentModuleService.listRefunds(
  {
    id: ["ref_123", "ref_321"],
  },
  {
    relations: ["payment"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableRefundProps
The filters to apply on the retrieved refunds.
configFindConfig<RefundDTO>
The configurations determining how the refund is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a refund.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RefundDTO[]>Required
The list of refunds.

processEvent​

This method handles a webhook event with the associated payment provider.

Learn more about handling webhook events in this guide

Example​

In the following example, req is an instance of MedusaRequest:

await paymentModuleService.processEvent({
  provider: "stripe",
  payload: {
    data: req.body,
    rawData: req.rawBody,
    headers: req.headers,
  },
})

Parameters​

dataProviderWebhookPayloadRequired
The webhook event's details.

Returns​

PromisePromise<void>Required
Resolves when the webhook event is handled successfully.
Was this section helpful?
© 2025 Medusa, Inc. All rights reserved.