Payment Method API

Overview

Payment methods are registered in-process at bootstrap (registerPaymentMethod) and each one carries an optional validator that is evaluated against the current cart. Because availability depends on cart state — most visibly the grand total — the list is exposed as a GraphQL field on the cart, not as a static REST collection.

Removed endpoint

GET /api/paymentMethods does not exist. Use the GraphQL query below.

List Available Payment Methods (GraphQL)

Query Cart.availablePaymentMethods against the storefront endpoint POST /graphql.

query AvailablePaymentMethods($cartId: String!) {
  cart(id: $cartId) {
    availablePaymentMethods {
      code
      name
    }
  }
}

{
  "data": {
    "cart": {
      "availablePaymentMethods": [
        { "code": "cod", "name": "Cash On Delivery" },
        { "code": "paypal", "name": "PayPal" },
        { "code": "stripe", "name": "Credit Card" }
      ]
    }
  }
}

Zero-Total Carts

A cart whose grand_total is 0 — fully discounted, free products, a 100% coupon — collapses to exactly one available method, the built-in zero_checkout:

{
  "data": {
    "cart": {
      "availablePaymentMethods": [
        { "code": "zero_checkout", "name": "No payment required" }
      ]
    }
  }
}

Every gateway method is filtered out centrally, and zero_checkout hides itself whenever the total is above zero or unknown. A storefront that hardcodes a gateway code will fail on these carts, so always render the returned list rather than a fixed set.

---

Apply a Payment Method to a Cart

Request Schema (application/json)

Field Name	Field Type	Required
method_code	string	Yes

POST/api/carts/{cart_id}/paymentMethods

cURL

curl
  -H "Accept: application/json"
  --data-raw "<JSON DATA>"
  https://<your domain>/api/carts/{cart_id}/paymentMethods

JavaScript

fetch('https://<your domain>/api/carts/{cart_id}/paymentMethods', {
  headers: {
    'Accept': 'application/json',
  },
  body: <JSON DATA>
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "method": {
    "code": "paypal",
    "name": "Paypal"
  }
}
}

Path Parameters

Parameter	Type	Required	Description
cart_id	string	Yes	The UUID of the cart

Registering a Payment Method

Custom gateways are added from a module's bootstrap.ts with registerPaymentMethod. See the payment method development guide for the full contract.