Cash on delivery, shipped

Cash on delivery is one of the tenders The Merchant Engine ships with, next to manual bank transfer and gift cards. A store owner switches it on in the admin, the public checkout endpoint publishes it with its translated name, and the order records the tender it was placed with. No card gateway is required to take an order.

How it works

The tender is a row, not a plugin. Payment methods live in the database with a code, a provider family, a translated name and description, and an active flag. Cash on delivery is the cod provider. The admin's payment methods screen is where a store owner turns it on or off.

The storefront learns the tenders from one public route. GET /v1/checkout/settings returns whether a guest may check out, which fields the operator requires and the tenders on offer. It is the only route that publishes payment methods, and the code sent back on the order has to come from that list. The route is Cache-Control: no-store on purpose, so an operator switching a tender off applies on the next page load.

The response, from a local install serving the demo fixture
GET /v1/checkout/settings

{
  "data": {
    "checkout": {
      "guestCheckoutEnabled": true,
      "requiredFields": ["email"],
      "termsOfServiceUrl": null,
      "postPurchaseRedirectUrl": null,
      "checkoutMessage": null
    },
    "paymentMethods": [
      {
        "code": "cod",
        "name": "Cash on delivery",
        "description": "Pay the courier in cash when your order arrives.",
        "provider": "cod",
        "sortOrder": 0
      }
    ]
  }
}

The order keeps what it was placed with. The payment method name, the shipping method name and the line labels are snapshotted onto the order in the locale it was placed in, so a French order still reads Paiement à la livraison a year later even if the store renames the tender. Stock is decremented atomically at order creation, so two customers cannot both take the last unit.

What is not there. The first release ships no card gateway. The payments module has the seams for one and the docs carry a recipe for adding a provider, but cash on delivery, manual bank transfer and gift cards are the tenders that work today. There is also no cash-on-delivery surcharge field: the customer pays the order total on the doorstep, and any delivery fee comes from the shipping zone.

Where to read the detail

Questions

Is cash on delivery a plugin?

No. It is one of the payment methods the engine ships with, alongside manual bank transfer and gift cards. A store owner switches it on in the admin and it appears at checkout.

How does the storefront know the store takes cash?

It reads GET /v1/checkout/settings, a public route that returns the tenders the store offers with their translated names and descriptions. The code the customer picks goes back on the order.

Can a store run without any card gateway at all?

Yes, and that is the shipped configuration. Cash on delivery, manual bank transfer and gift cards are the live tenders in the first release. No card gateway ships with it.

Does the engine add a cash-on-delivery surcharge?

No. There is no surcharge field on a payment method. What the customer pays on delivery is the order total, and any delivery fee comes from the shipping zone and method the store configured.

What stops a double order when the customer taps twice?

Every order creation carries an idempotency key, and a repeat of the same request with the same key returns the first order instead of placing a second one. See idempotent checkout.

Does the customer get anything to keep?

An order confirmation email from the store’s own domain, an order they can track, and an invoice PDF rendered in their locale and direction.

Last updated . Every claim on this page is read from a published source and cited beside it.