Accept Payment Flow

In this document, you’ll learn how to implement an accept-payment flow using the Payment Module's main service.

Flow Overview#

1. Create a Payment Collection#

A payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.

For example:

Code
1const paymentCollection =2  await paymentModuleService.createPaymentCollections({3    region_id: "reg_123",4    currency_code: "usd",5    amount: 5000,6  })

Then, create a link between the payment collection and the resource it's storing payment details for, such as a cart in the Cart Module:

Code
1import { 2  ContainerRegistrationKeys,3  Modules,4} from "@medusajs/framework/utils"5
6// ...7
8// resolve the remote link9const remoteLink = container.resolve(10  ContainerRegistrationKeys11)12
13remoteLink.create({14  [Modules.CART]: {15    cart_id: "cart_123",16  },17  [Modules.PAYMENT]: {18    payment_collection_id: paymentCollection.id,19  },20})

2. Create Payment Sessions#

The payment collection has one or more payment sessions, each being a payment amount to be authorized by a payment provider.

So, after creating the payment collection, create at least one payment session for a provider.

For example:

Code
1const paymentSession =2  await paymentModuleService.createPaymentSession(3    paymentCollection.id,4    {5      provider_id: "stripe",6      currency_code: "usd",7      amount: 5000,8      data: {9        // any necessary data for the10        // payment provider11      },12    }13  )

3. Authorize Payment Session#

Once the customer chooses a payment session, start the authorization process. This may involve some action performed by the third-party payment provider, such as entering a 3DS code.

For example:

Code
1const payment =2  await paymentModuleService.authorizePaymentSession(3    paymentSession.id,4    {}5  )

When the payment authorization is successful, a payment is created and returned.

Handling Additional Action#

If the payment authorization isn’t successful, whether because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error.

In that case, you can catch that error and, if the session's status property is requires_more, handle the additional action, then retry the authorization.

For example:

Code
1try {2  const payment =3    await paymentModuleService.authorizePaymentSession(4      paymentSession.id,5      {}6    )7} catch (e) {8  // retrieve the payment session again9  const updatedPaymentSession = (10    await paymentModuleService.listPaymentSessions({11      id: [paymentSession.id],12    })13  )[0]14
15  if (updatedPaymentSession.status === "requires_more") {16    // TODO perform required action17    // TODO authorize payment again.18  }19}

4. Payment Flow Complete#

The payment flow is complete once the payment session is authorized and the payment is created.

You can then use the payment to capture the amount using the capturePayment method. You can also refund captured amounts using the refundPayment method.