Payment Session

In this document, you’ll learn what a payment session is.

What's a Payment Session?#

A payment session, represented by the PaymentSession data model, is a payment amount to be authorized. It’s associated with a payment provider that handles authorizing it.

A payment collection can have multiple payment sessions. Using this feature, you can implement payment in installments or payments using multiple providers.

data Property#

Payment providers may need additional data to process the payment later. For example, the ID of the session in the third-party provider.

The PaymentSession data model has a data property used to store that data. It's set by the payment provider in Medusa when the payment is initialized.

Then, when the payment session is authorized, the data property is used by the payment provider in Medusa to process the payment with the third-party provider.

data Property in the Storefront#

This data property is accessible in the storefront as well. So, only store in it data that can be publicly shared, and data that is useful in the storefront.

For example, you can also store the client token used to initialize the payment session in the storefront with the third-party provider.

Update Client Data from the Storefront#

Some payment providers collect details in the storefront after you initialize the payment session. For example, a provider's checkout component may return a payment method ID that the provider needs to authorize the payment.

To pass these details to the payment session, use the Update Payment Session API route or the JS SDK's sdk.store.payment.updatePaymentSession method. Medusa sets the client_data you pass as the payment session's data.client property, then passes the updated data to the payment provider's updatePayment method. The rest of the data property is owned by the payment provider, and you can't change it from the storefront.

sdk.store.payment.updatePaymentSession(
  "paycol_123",
  "payses_123",
  {
    client_data: {
      payment_method: "pm_123",
    },
  }
)
.then(({ payment_collection }) => {
  console.log(payment_collection)
})

You can only update a payment session whose status is pending, requires_more, or error. Medusa throws an error for other statuses, since they indicate that the authorization is in progress or done.

Under the hood, the API route uses the updatePaymentSessionClientDataWorkflow. You can also execute this workflow in your custom flows.

Payment Session Status#

The status property of a payment session indicates its current status. Its value can be:

• pending: The payment session is awaiting authorization.
• requires_more: The payment session requires an action before it's authorized. For example, to enter a 3DS code.
• authorized: The payment session is authorized.
• error: An error occurred while authorizing the payment.
• canceled: The authorization of the payment session has been canceled.
• pending_authorization: The payment authorization is deferred and will complete asynchronously. This is used for payment methods like bank transfers, payment links, or vouchers (for example, OXXO or boleto) where the customer completes the payment outside of the checkout flow. An order can still be created while the session is in this status, and the session transitions to authorized once the payment provider confirms receipt. Available since Medusa v2.17.2