Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Removed redundant payments endpoints
Damian Legawiec2588c050fff4
diff --git a/packages/sdk/README.md b/packages/sdk/README.mdindex e17bca199f..64f02d846c 100644--- a/packages/sdk/README.md+++ b/packages/sdk/README.md@@ -299,18 +299,11 @@ await client.carts.storeCredits.remove('cart_xxx', options);```typescriptconst options = { spreeToken: cart.token };-// Get available payment methods for the current checkout-const methods = await client.carts.paymentMethods.list('cart_xxx', options);-// Each method includes `session_required` flag:+// Payment methods and payments are included in the cart response.+// Each payment method includes `session_required` flag:// - true -> use paymentSessions (Stripe, Adyen, PayPal, etc.)// - false -> use payments.create (Check, Cash on Delivery, Bank Transfer, etc.)-// List payments on the cart-const payments = await client.carts.payments.list('cart_xxx', options);--// Get a specific payment-const payment = await client.carts.payments.get('cart_xxx', paymentId, options);-// Create a payment for a non-session payment method// (e.g. Check, Cash on Delivery, Bank Transfer, Purchase Order)const payment = await client.carts.payments.create('cart_xxx', {@@ -559,8 +552,7 @@ The SDK uses a resource builder pattern for nested resources:| `carts` | `items` | `create`, `update`, `delete` || `carts` | `couponCodes` | `apply`, `remove` || `carts` | `fulfillments` | `list`, `update` |-| `carts` | `paymentMethods` | `list` |-| `carts` | `payments` | `list`, `get`, `create` |+| `carts` | `payments` | `create` || `carts` | `paymentSessions` | `create`, `get`, `update`, `complete` || `carts` | `storeCredits` | `apply`, `remove` || `customer` | `addresses` | `list`, `get`, `create`, `update`, `delete` |@@ -578,7 +570,7 @@ Example:await client.carts.items.create(cartId, params, options);await client.carts.couponCodes.apply(cartId, code, options);await client.carts.fulfillments.update(cartId, fulfillmentId, params, options);-await client.carts.payments.list(cartId, options);+await client.carts.payments.create(cartId, params, options);await client.carts.paymentSessions.create(cartId, params, options);await client.carts.storeCredits.apply(cartId, amount, options);diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.tsindex 969d64479f..7c1299fcd8 100644--- a/packages/sdk/src/store-client.ts+++ b/packages/sdk/src/store-client.ts@@ -38,7 +38,6 @@ import type {Market,Category,Payment,- PaymentMethod,PaymentSession,PaymentSetupSession,Fulfillment,@@ -475,52 +474,10 @@ export class StoreClient {),},- /**- * Nested resource: Payment methods- */- paymentMethods: {- /**- * List available payment methods for the cart- * @param cartId - Cart prefixed ID- */- list: (cartId: string, options?: RequestOptions): Promise<ListResponse<PaymentMethod>> =>- this.request<ListResponse<PaymentMethod>>(- 'GET',- `/carts/${cartId}/payment_methods`,- options- ),- },-/*** Nested resource: Payments*/payments: {- /**- * List payments for the cart- * @param cartId - Cart prefixed ID- */- list: (cartId: string, options?: RequestOptions): Promise<ListResponse<Payment>> =>- this.request<ListResponse<Payment>>(- 'GET',- `/carts/${cartId}/payments`,- options- ),-- /**- * Get a payment by ID- * @param cartId - Cart prefixed ID- */- get: (- cartId: string,- paymentId: string,- options?: RequestOptions- ): Promise<Payment> =>- this.request<Payment>(- 'GET',- `/carts/${cartId}/payments/${paymentId}`,- options- ),-/*** Create a payment for a non-session payment method (e.g. Check, Cash on Delivery, Bank Transfer).* For session-based payment methods (e.g. Stripe, PayPal), use carts.paymentSessions.create() instead.@@ -676,7 +633,7 @@ export class StoreClient {* Get current customer profile*/get: (options?: RequestOptions): Promise<Customer> =>- this.request<Customer>('GET', '/customer', options),+ this.request<Customer>('GET', '/customers/me', options),/*** Update current customer profile@@ -697,7 +654,7 @@ export class StoreClient {},options?: RequestOptions): Promise<Customer> =>- this.request<Customer>('PATCH', '/customer', {+ this.request<Customer>('PATCH', '/customers/me', {...options,body: params,}),@@ -754,19 +711,6 @@ export class StoreClient {* Delete an address*/delete: (id: string, options?: RequestOptions): Promise<void> =>-- /**- * Mark an address as default billing or shipping- */- markAsDefault: (- id: string,- kind: 'billing' | 'shipping',- options?: RequestOptions- ): Promise<Address> =>- this.request<Address>('PATCH', `/customer/addresses/${id}/mark_as_default`, {- ...options,- body: { kind },- }),this.request<void>('DELETE', `/customers/me/addresses/${id}`, options),},diff --git a/packages/sdk/tests/cart.test.ts b/packages/sdk/tests/cart.test.tsindex 5f65bfcf30..21c1593335 100644--- a/packages/sdk/tests/cart.test.ts+++ b/packages/sdk/tests/cart.test.ts@@ -129,13 +129,6 @@ describe('carts', () => {});});- describe('paymentMethods', () => {- it('lists payment methods', async () => {- const result = await client.carts.paymentMethods.list('cart_1', opts);- expect(result.data).toBeDefined();- });- });-describe('storeCredits', () => {it('applies store credit', async () => {const result = await client.carts.storeCredits.apply('cart_1', 10, opts);diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.tsindex aabab18204..b1e1df342d 100644--- a/packages/sdk/tests/mocks/handlers.ts+++ b/packages/sdk/tests/mocks/handlers.ts@@ -260,51 +260,7 @@ export const handlers = [HttpResponse.json(fixtures.cart)),- // Carts > Payment Methods- http.get(`${API_PREFIX}/carts/:cartId/payment_methods`, () =>- HttpResponse.json({ data: [], meta: { count: 0 } })- ),-// Carts > Payments- http.get(`${API_PREFIX}/carts/:cartId/payments`, () =>- HttpResponse.json({- data: [{- id: 'py_1',- payment_method_id: 'pm_1',- state: 'checkout',- response_code: null,- number: 'P1234',- amount: '19.99',- display_amount: '$19.99',- source_type: 'credit_card',- source_id: 'card_1',- source: { id: 'card_1', brand: 'visa', last4: '4242', name: 'Test User', month: '12', year: '2028' },- created_at: '2026-02-17T00:00:00.000Z',- updated_at: '2026-02-17T00:00:00.000Z',- payment_method: { id: 'pm_1', name: 'Credit Card', description: null, type: 'Spree::Gateway::Bogus', session_required: true },- }],- meta: { count: 1 },- })- ),-- http.get(`${API_PREFIX}/carts/:cartId/payments/:id`, () =>- HttpResponse.json({- id: 'py_1',- payment_method_id: 'pm_1',- state: 'checkout',- response_code: null,- number: 'P1234',- amount: '19.99',- display_amount: '$19.99',- source_type: 'credit_card',- source_id: 'card_1',- source: { id: 'card_1', brand: 'visa', last4: '4242', name: 'Test User', month: '12', year: '2028' },- created_at: '2026-02-17T00:00:00.000Z',- updated_at: '2026-02-17T00:00:00.000Z',- payment_method: { id: 'pm_1', name: 'Credit Card', description: null, type: 'Spree::Gateway::Bogus', session_required: true },- })- ),-http.post(`${API_PREFIX}/carts/:cartId/payments`, () =>HttpResponse.json({id: 'py_2',diff --git a/packages/sdk/tests/payments.test.ts b/packages/sdk/tests/payments.test.tsindex 1d7dd8de64..bb484ff13f 100644--- a/packages/sdk/tests/payments.test.ts+++ b/packages/sdk/tests/payments.test.ts@@ -7,54 +7,6 @@ describe('payments', () => {beforeAll(() => { client = createTestClient(); });const opts = { token: 'user-jwt' };- describe('list', () => {- it('returns payments for the cart', async () => {- const result = await client.carts.payments.list('cart_1', opts);- expect(result.data).toHaveLength(1);- expect(result.data[0].id).toBe('py_1');- expect(result.data[0].state).toBe('checkout');- expect(result.data[0].amount).toBe('19.99');- });-- it('includes source_type, source_id, and source for credit card payments', async () => {- const result = await client.carts.payments.list('cart_1', opts);- const payment = result.data[0];- expect(payment.source_type).toBe('credit_card');- expect(payment.source_id).toBe('card_1');- expect(payment.source).toBeDefined();- expect(payment.source!.id).toBe('card_1');- if (payment.source_type === 'credit_card') {- const source = payment.source as { brand: string; last4: string };- expect(source.brand).toBe('visa');- expect(source.last4).toBe('4242');- }- });-- it('includes payment_method association', async () => {- const result = await client.carts.payments.list('cart_1', opts);- expect(result.data[0].payment_method.id).toBe('pm_1');- expect(result.data[0].payment_method.name).toBe('Credit Card');- });- });-- describe('get', () => {- it('returns a payment by ID', async () => {- const result = await client.carts.payments.get('cart_1', 'py_1', opts);- expect(result.id).toBe('py_1');- expect(result.state).toBe('checkout');- expect(result.number).toBe('P1234');- expect(result.payment_method_id).toBe('pm_1');- });-- it('includes source details', async () => {- const result = await client.carts.payments.get('cart_1', 'py_1', opts);- expect(result.source_type).toBe('credit_card');- expect(result.source_id).toBe('card_1');- expect(result.source).toBeDefined();- expect(result.source!.id).toBe('card_1');- });- });-describe('create', () => {it('creates a payment for a non-session payment method', async () => {const result = await client.carts.payments.create(diff --git a/spree/api/app/controllers/spree/api/v3/store/carts/payment_methods_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/payment_methods_controller.rbdeleted file mode 100644index 879401b1da..0000000000--- a/spree/api/app/controllers/spree/api/v3/store/carts/payment_methods_controller.rb+++ /dev/null@@ -1,24 +0,0 @@-module Spree- module Api- module V3- module Store- module Carts- class PaymentMethodsController < Store::BaseController- include Spree::Api::V3::CartResolvable-- before_action :find_cart!-- # GET /api/v3/store/carts/:cart_id/payment_methods- def index- methods = @cart.collect_frontend_payment_methods- render json: {- data: methods.map { |m| Spree.api.payment_method_serializer.new(m, params: serializer_params).to_h },- meta: { count: methods.size }- }- end- end- end- end- end- end-enddiff --git a/spree/api/app/controllers/spree/api/v3/store/carts/payments_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/payments_controller.rbindex 9f02a367b0..3cec092031 100644--- a/spree/api/app/controllers/spree/api/v3/store/carts/payments_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/store/carts/payments_controller.rb@@ -3,9 +3,11 @@ module Spreemodule V3module Storemodule Carts- class PaymentsController < Store::ResourceController+ class PaymentsController < Store::BaseControllerinclude Spree::Api::V3::CartResolvable+ before_action :find_cart!+# POST /api/v3/store/carts/:cart_id/payments# Creates a payment for non-session payment methods (e.g. Check, Cash on Delivery, Bank Transfer)def create@@ -19,7 +21,7 @@ module Spree)end- unless payment_method.available_for_order?(@parent)+ unless payment_method.available_for_order?(@cart)return render_error(code: 'payment_method_unavailable',message: Spree.t('api.v3.payments.method_unavailable'),@@ -27,43 +29,20 @@ module Spree)end- amount = params[:amount].presence || @parent.total_minus_store_credits+ amount = params[:amount].presence || @cart.total_minus_store_credits- @payment = @parent.payments.build(+ @payment = @cart.payments.build(payment_method: payment_method,amount: amount,metadata: params[:metadata].present? ? params[:metadata].to_unsafe_h : {})if @payment.save- render json: serialize_resource(@payment), status: :created+ render json: Spree.api.payment_serializer.new(@payment, params: serializer_params).to_h, status: :createdelserender_errors(@payment.errors)endend-- protected-- def set_parent- find_cart!- @parent = @cart- end-- def parent_association- :payments- end-- def model_class- Spree::Payment- end-- def serializer_class- Spree.api.payment_serializer- end-- # Authorization is handled by find_cart! in set_parent- def authorize_resource!(*)- endendendenddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex b744c3b027..a2395d4aa5 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -40,8 +40,7 @@ Spree::Core::Engine.add_routes doresources :items, only: [:create, :update, :destroy], controller: 'carts/items'resources :coupon_codes, only: [:create, :destroy], controller: 'carts/coupon_codes'resources :fulfillments, only: [:index, :update], controller: 'carts/fulfillments'- resources :payment_methods, only: [:index], controller: 'carts/payment_methods'- resources :payments, only: [:index, :show, :create], controller: 'carts/payments'+ resources :payments, only: [:create], controller: 'carts/payments'resources :payment_sessions, only: [:create, :show, :update], controller: 'carts/payment_sessions' domember dopatch :completediff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/payment_methods_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/payment_methods_controller_spec.rbdeleted file mode 100644index db0cd9fe20..0000000000--- a/spree/api/spec/controllers/spree/api/v3/store/carts/payment_methods_controller_spec.rb+++ /dev/null@@ -1,64 +0,0 @@-require 'spec_helper'--RSpec.describe Spree::Api::V3::Store::Carts::PaymentMethodsController, type: :controller do- render_views-- include_context 'API v3 Store'-- let!(:order) { create(:order_with_line_items, user: user, store: store, state: 'payment') }- let!(:payment_method) { create(:credit_card_payment_method, stores: [store], display_on: 'both') }- let!(:backend_only_pm) { create(:credit_card_payment_method, stores: [store], display_on: 'back_end') }-- before do- request.headers['X-Spree-Api-Key'] = api_key.token- request.headers['Authorization'] = "Bearer #{jwt_token}"- end-- describe 'GET #index' do- it 'returns available payment methods for the cart' do- get :index, params: { cart_id: order.prefixed_id }-- expect(response).to have_http_status(:ok)- expect(json_response['data'].map { |pm| pm['id'] }).to include(payment_method.prefixed_id)- end-- it 'excludes backend-only payment methods' do- get :index, params: { cart_id: order.prefixed_id }-- expect(json_response['data'].map { |pm| pm['id'] }).not_to include(backend_only_pm.prefixed_id)- end-- it 'includes session_required in the response' do- get :index, params: { cart_id: order.prefixed_id }-- pm = json_response['data'].find { |p| p['id'] == payment_method.prefixed_id }- expect(pm).to have_key('session_required')- end-- it 'includes payment method count in meta' do- get :index, params: { cart_id: order.prefixed_id }-- expect(json_response['meta']['count']).to be_present- end-- context 'with spree token (guest)' do- let(:guest_order) { create(:order_with_line_items, store: store, user: nil, state: 'payment') }-- before { request.headers['Authorization'] = nil }-- it 'returns payment methods with valid spree token' do- request.headers['x-spree-token'] = guest_order.token- get :index, params: { cart_id: guest_order.prefixed_id }-- expect(response).to have_http_status(:ok)- expect(json_response['data']).to be_present- end-- it 'returns forbidden without spree token' do- get :index, params: { cart_id: guest_order.prefixed_id }-- expect(response).to have_http_status(:forbidden)- end- end- end-enddiff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rbindex 00ae8a5c68..4300a8d7a4 100644--- a/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/payments_controller_spec.rb@@ -6,80 +6,12 @@ RSpec.describe Spree::Api::V3::Store::Carts::PaymentsController, type: :controllinclude_context 'API v3 Store'let(:order) { create(:order_with_line_items, user: user, store: store, state: 'payment') }- let(:payment_method) { create(:credit_card_payment_method, stores: [store]) }- let!(:payment) { create(:payment, order: order, payment_method: payment_method, amount: order.total) }before dorequest.headers['X-Spree-Api-Key'] = api_key.tokenrequest.headers['Authorization'] = "Bearer #{jwt_token}"end- describe 'GET #index' do- it 'returns a list of payments for the cart' do- get :index, params: { cart_id: order.prefixed_id }-- expect(response).to have_http_status(:ok)- expect(json_response['data'].size).to eq(1)- expect(json_response['data'].first['id']).to eq(payment.prefixed_id)- end-- it 'includes payment method information' do- get :index, params: { cart_id: order.prefixed_id }-- expect(json_response['data'].first['payment_method_id']).to eq(payment_method.prefixed_id)- end-- context 'with spree token (guest)' do- let(:guest_order) { create(:order_with_line_items, user: nil, store: store, state: 'payment') }- let!(:guest_payment) { create(:payment, order: guest_order, payment_method: payment_method) }-- before { request.headers['Authorization'] = nil }-- it 'returns payments with valid spree token' do- request.headers['x-spree-token'] = guest_order.token- get :index, params: { cart_id: guest_order.prefixed_id }-- expect(response).to have_http_status(:ok)- expect(json_response['data'].size).to eq(1)- end-- it 'returns forbidden without spree token' do- get :index, params: { cart_id: guest_order.prefixed_id }-- expect(response).to have_http_status(:forbidden)- end- end- end-- describe 'GET #show' do- it 'returns a single payment' do- get :show, params: { cart_id: order.prefixed_id, id: payment.to_param }-- expect(response).to have_http_status(:ok)- expect(json_response['id']).to eq(payment.prefixed_id)- expect(json_response['status']).to eq(payment.state)- expect(json_response['amount']).to eq(payment.amount.to_s)- end-- context 'error handling' do- it 'returns not found for non-existent payment' do- get :show, params: { cart_id: order.prefixed_id, id: 'py_invalid' }-- expect(response).to have_http_status(:not_found)- end-- it 'returns not found for payment from another order' do- other_user = create(:user)- other_order = create(:order_with_line_items, user: other_user, store: store, state: 'payment')- other_payment = create(:payment, order: other_order, payment_method: payment_method, amount: other_order.total)-- get :show, params: { cart_id: order.prefixed_id, id: other_payment.to_param }-- expect(response).to have_http_status(:not_found)- end- end- end-describe 'POST #create' dolet(:check_payment_method) { create(:check_payment_method, stores: [store]) }diff --git a/spree/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb b/spree/api/spec/integration/spree/api/v3/store/payment_methods_spec.rbdeleted file mode 100644index 7af62db064..0000000000--- a/spree/api/spec/integration/spree/api/v3/store/payment_methods_spec.rb+++ /dev/null@@ -1,57 +0,0 @@-# frozen_string_literal: true--require 'swagger_helper'--RSpec.describe 'Cart Payment Methods API', type: :request, swagger_doc: 'api-reference/store.yaml' do- include_context 'API v3 Store'-- let!(:order) { create(:order_with_line_items, store: store, user: user, state: 'payment') }- let!(:payment_method) { create(:credit_card_payment_method, stores: [store], display_on: 'both') }- let!(:backend_only_pm) { create(:credit_card_payment_method, stores: [store], display_on: 'back_end') }- let(:cart_id) { order.prefixed_id }-- path '/api/v3/store/carts/{cart_id}/payment_methods' do- get 'List available payment methods' do- tags 'Carts'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Returns payment methods available for the current cart based on store configuration and order state.'-- sdk_example <<~JS- const methods = await client.carts.paymentMethods.list('cart_abc123', {- bearerToken: '<token>',- })- JS-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: 'Authorization', in: :header, type: :string, required: false,- description: 'Bearer token for authenticated customers'- parameter name: :cart_id, in: :path, type: :string, required: true, description: 'Cart prefixed ID (e.g., cart_abc123)'- parameter name: 'x-spree-token', in: :header, type: :string, required: false,- description: 'Order token for guest access'-- response '200', 'payment methods found' do- let(:'x-spree-api-key') { api_key.token }- let(:'Authorization') { "Bearer #{jwt_token}" }-- schema type: :object,- properties: {- data: { type: :array, items: { '$ref' => '#/components/schemas/PaymentMethod' } },- meta: {- type: :object,- properties: {- count: { type: :integer }- }- }- }-- run_test! do |response|- data = JSON.parse(response.body)- # Only frontend-visible payment methods should be returned- expect(data['data'].map { |pm| pm['id'] }).to include(payment_method.prefixed_id)- expect(data['data'].map { |pm| pm['id'] }).not_to include(backend_only_pm.prefixed_id)- end- end- end- end-enddiff --git a/spree/api/spec/integration/spree/api/v3/store/payments_spec.rb b/spree/api/spec/integration/spree/api/v3/store/payments_spec.rbindex e03c22feda..185b86939b 100644--- a/spree/api/spec/integration/spree/api/v3/store/payments_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/payments_spec.rb@@ -9,40 +9,6 @@ RSpec.describe 'Cart Payments API', type: :request, swagger_doc: 'api-reference/let(:cart_id) { order.prefixed_id }path '/api/v3/store/carts/{cart_id}/payments' do- get 'List payments' do- tags 'Carts'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Returns all payments for the cart.'-- sdk_example <<~JS- const payments = await client.carts.payments.list('cart_abc123', {- bearerToken: '<token>',- })- JS-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: 'Authorization', in: :header, type: :string, required: false- parameter name: :cart_id, in: :path, type: :string, required: true, description: 'Cart prefixed ID (e.g., cart_abc123)'- parameter name: 'x-spree-token', in: :header, type: :string, required: false-- response '200', 'payments listed' do- let!(:payment) do- pm = create(:check_payment_method, stores: [store])- create(:payment, order: order, payment_method: pm, amount: order.total, state: 'checkout')- end- let(:'x-spree-api-key') { api_key.token }- let(:'Authorization') { "Bearer #{jwt_token}" }-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['data'].size).to eq(1)- expect(data['data'][0]['id']).to eq(payment.prefixed_id)- expect(data['meta']['count']).to eq(1)- end- end- end-post 'Create payment' dolet(:check_method) { create(:check_payment_method, stores: [store]) }