Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Payment Collections
  • Introduction
  • Authentication
  • HTTP Compression
  • Publishable API Key
  • Expanding Fields
  • Selecting Fields
  • Query Parameter Types
  • Pagination
  • Currencies
    • List Currencies
      GET
    • Get a Currency
      GET
  • Payment Providers
    • List Payment Providers
      GET
  • Return Reasons
    • List Return Reasons
      GET
    • Get a Return Reason
      GET
  • Auth
    • Retrieve Registration JWT Token
      POST
    • Authenticate Customer
      POST
    • Generate Reset Password Token for Customer
      POST
    • Refresh Authentication Token
      POST
    • Validate Authentication Callback
      POST
    • Delete Authentication Session
      DELETE
    • Set Authentication Session
      POST
    • Reset a Customer's Password
      POST
  • Collections
    • List Collections
      GET
    • Get a Collection
      GET
  • Regions
    • List Regions
    • Get a Region
  • Products
    • List Products
    • Get a Product
  • Customers
    • Get Logged-in Customer
    • Update Customer
    • Create Address for Logged-In Customer
    • List Customer's Addresses
    • Get Customer's Address
    • Update Customer's Address
    • Remove Customer's Address
    • Register Customer
  • Product Tags
    • List Product Tags
    • Get a Product Tag
  • Returns
    • Create Return
  • Product Types
    • Get a Product Type
    • List Product Types
  • Product Categories
    • List Product Categories
    • Get a Product Category
  • Carts
    • Create Cart
    • Set Cart's Customer
    • Add Shipping Method to Cart
    • Add Line Item to Cart
    • Calculate Cart Taxes
    • Get a Cart
    • Update a Cart
    • Update a Line Item in a Cart
    • Remove Line Item from Cart
    • Complete Cart
    • Add Promotions to Cart
    • Remove Promotions from Cart
  • Orders
    • List Logged-in Customer's Orders
    • Request Order Transfer
    • Get an Order
    • Cancel Order Transfer
    • Decline Order Transfer
    • Accept Order Transfer
  • Payment Collections
    • Initialize Payment Session of a Payment Collection
      POST
    • Create Payment Collection
      POST
  • Shipping Options
    • Calculate Shipping Option Price
    • List Shipping Options for Cart
  1. Payment Collections

Initialize Payment Session of a Payment Collection

POST
/store/payment-collections/{id}/payment-sessions
Payment Collections
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.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST '{{BASE_URL}}/store/payment-collections//payment-sessions' \
--header 'x-publishable-api-key;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "provider_id": "pp_stripe_stripe",
    "data": {}
}'
Response Response Example
200 - Example 1
{
    "payment_collection": {
        "id": "string",
        "currency_code": "string",
        "amount": 0,
        "authorized_amount": 0,
        "captured_amount": 0,
        "refunded_amount": 0,
        "completed_at": "2019-08-24T14:15:22Z",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "metadata": {},
        "status": "canceled",
        "payment_providers": [
            {
                "id": "string"
            }
        ],
        "payment_sessions": [
            {
                "id": "string",
                "amount": 0,
                "currency_code": "usd",
                "provider_id": "string",
                "authorized_at": "2019-08-24T14:15:22Z",
                "payment_collection": {},
                "data": {},
                "status": "authorized",
                "context": {
                    "customer": {
                        "id": "cus_123"
                    }
                },
                "payment": {
                    "id": "string",
                    "amount": 0,
                    "authorized_amount": 0,
                    "currency_code": "string",
                    "provider_id": "string",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "captured_at": "2019-08-24T14:15:22Z",
                    "canceled_at": "2019-08-24T14:15:22Z",
                    "captured_amount": 0,
                    "refunded_amount": 0,
                    "payment_collection": {},
                    "payment_session": {},
                    "data": {},
                    "captures": [
                        {
                            "id": "string",
                            "amount": 0,
                            "created_at": "2019-08-24T14:15:22Z",
                            "created_by": "string",
                            "payment": {}
                        }
                    ],
                    "refunds": [
                        {
                            "id": "string",
                            "amount": 0,
                            "refund_reason_id": "string",
                            "note": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "created_by": "string",
                            "payment": {},
                            "refund_reason": {
                                "id": "string",
                                "label": "string",
                                "description": "string",
                                "metadata": {},
                                "created_at": "2019-08-24T14:15:22Z",
                                "updated_at": "2019-08-24T14:15:22Z"
                            }
                        }
                    ]
                }
            }
        ],
        "payments": [
            {
                "id": "string",
                "amount": 0,
                "authorized_amount": 0,
                "currency_code": "string",
                "provider_id": "string",
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "captured_at": "2019-08-24T14:15:22Z",
                "canceled_at": "2019-08-24T14:15:22Z",
                "captured_amount": 0,
                "refunded_amount": 0,
                "payment_collection": {},
                "payment_session": {},
                "data": {},
                "captures": [
                    {
                        "id": "string",
                        "amount": 0,
                        "created_at": "2019-08-24T14:15:22Z",
                        "created_by": "string",
                        "payment": {}
                    }
                ],
                "refunds": [
                    {
                        "id": "string",
                        "amount": 0,
                        "refund_reason_id": "string",
                        "note": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "created_by": "string",
                        "payment": {},
                        "refund_reason": {
                            "id": "string",
                            "label": "string",
                            "description": "string",
                            "metadata": {},
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z"
                        }
                    }
                ]
            }
        ]
    }
}

Request

Path Params
id
string 
required
The payment collection's ID.
Query Params
fields
string 
fields
optional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + 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.
Header Params
x-publishable-api-key
string 
required
Publishable API Key created in the Medusa Admin.
Body Params application/json
The payment session's details.
provider_id
string 
provider_id
required
The ID of the payment provider the customer chose.
Example:
pp_stripe_stripe
data
object 
optional
Any data necessary for the payment provider to process the payment.
Examples

Responses

🟢200OK
application/json
OK
Body
The payment collection's details.
payment_collection
object (StorePaymentCollection) 
required
The payment collection's details.
id
string 
id
required
The payment collection's ID.
currency_code
string 
currency_code
required
The payment collection's currency code.
amount
number 
amount
required
The total amount to be paid.
authorized_amount
number 
authorized_amount
optional
The total authorized amount of the collection's payments.
captured_amount
number 
captured_amount
optional
The total captured amount of the collection's payments.
refunded_amount
number 
refunded_amount
optional
The total refunded amount of the collection's payments.
completed_at
string <date-time>
completed_at
optional
The date the payment collection was completed.
created_at
string <date-time>
created_at
optional
The date the payment collection was created.
updated_at
string <date-time>
updated_at
optional
The date the payment collection was updated.
metadata
object 
optional
The payment collection's metadata, can hold custom key-value pairs.
status
enum<string> 
required
The payment collection's status.
Allowed values:
cancelednot_paidawaitingauthorizedpartially_authorized
payment_providers
array[object (StorePaymentProvider) {1}] 
required
The payment provider used to process the collection's payments and sessions.
payment_sessions
array[object (StorePaymentSession) {10}] 
optional
The payment collection's payment sessions.
payments
array[object (BasePayment) {16}] 
optional
The payment collection's payments.
🟠400Bad Request
🟠401Unauthorized
🟠404Record Not Found
🟠409409
🟠422Parameter Error
🔴500Server Error
Modified at 2025-06-17 04:21:30
Previous
Accept Order Transfer
Next
Create Payment Collection
Built with