Payment Collections API Routes
A cart must have a payment collection with an authorized payment session.
Use these API routes during checkout to set the cart's payment provider and authorize its payment session.
POST /store/payment-collections#
Create Payment Collection
Create a payment collection for a cart. This is used during checkout, where the payment collection holds the cart's payment sessions.
Authentication: none.
Header parameters
x-publishable-api-keystringx-medusa-localestringOptionalen-USQuery parameters
fieldsstringOptional+ it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.localestringOptionalen-USRequest body (application/json)
cart_idstringRequest examples
Responses
200 OK
payment_collectionobjectThe payment collection's details.
payment_collectionobject400, 401, 404, 409, 422, 500: an error response is returned.
POST /store/payment-collections/{id}/payment-sessions#
Initialize Payment Session of a Payment Collection
Initialize and add a payment session to a payment collection. This is used during checkout, where you create a payment collection for the cart, then initialize a payment session for the payment provider that the customer chooses.
It's highly recommended to have an amount greater than 0 in the payment collection, as some payment providers, such as Stripe, require a non-zero amount to create a payment session. Otherwise, an error will be thrown on the payment provider's side.
In cases where you want to create a payment session for a payment collection with an amount of 0, you can use the Manual System Payment Provider instead of third-party payment providers. The Manual System Payment Provider is built into Medusa and allows you to create payment sessions without interacting with an external payment provider.
Make sure to configure the Manual System Payment Provider in your store's region. Learn more in the Manage Region user guide.
Authentication: none.
Path parameters
idstringHeader parameters
x-publishable-api-keystringx-medusa-localestringOptionalen-USQuery parameters
fieldsstringOptional+ it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.localestringOptionalen-USRequest body (application/json)
provider_idstringpp_stripe_stripedataobjectOptionalRequest examples
Responses
200 OK
payment_collectionobjectThe payment collection's details.
payment_collectionobject400, 401, 404, 409, 422, 500: an error response is returned.
POST /store/payment-collections/{id}/payment-sessions/{session_id}#
Update Payment Session
Update a payment session's client data, such as payment details collected by the payment provider's checkout component. The data is merged into the session's data.client.
Authentication: none.
Path parameters
idstringsession_idstringHeader parameters
x-publishable-api-keystringx-medusa-localestringOptionalen-USQuery parameters
localestringOptionalen-USfieldsstringOptional+ it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.Request body (application/json)
client_dataobjectdata.client, such as payment details
collected by the provider's checkout component. Set a property to null to remove it.Request examples
Responses
200 OK
payment_collectionobjectThe payment collection's details.
payment_collectionobject400, 401, 404, 409, 422, 500: an error response is returned.