@wtree/payload-ecommerce-cod


Cash on Delivery (COD) payment adapter for Payload CMS Ecommerce Plugin. This adapter follows the same structure as the official Stripe adapter and integrates seamlessly with Payload's ecommerce plugin.

Features

- ✅ Full Payload CMS Ecommerce Plugin compatibility
- ✅ Configurable order limits (minimum/maximum)
- ✅ Regional availability controls
- ✅ Currency restrictions
- ✅ Optional service charges (percentage or fixed)
- ✅ Delivery status tracking
- ✅ Payment collection tracking
- ✅ Admin UI integration
- ✅ TypeScript support
- ✅ 80%+ test coverage

Installation

``bash
npm install @wtree/payload-ecommerce-cod
`

Usage

$3

Add the COD adapter to your Payload config:

`typescript
import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
import { codAdapter } from '@wtree/payload-ecommerce-cod'

export default buildConfig({
// ... other config
plugins: [
ecommercePlugin({
payments: {
paymentMethods: [
codAdapter({
label: 'Cash on Delivery',
minimumOrder: 100, // $1.00 in cents
maximumOrder: 50000, // $500.00 in cents
allowedRegions: ['US', 'CA', 'IN'],
supportedCurrencies: ['USD', 'INR'],
serviceChargePercentage: 2, // 2% service charge
fixedServiceCharge: 50, // $0.50 in cents
}),
],
},
}),
],
})
`

$3

Add the COD adapter client to your React app:

`typescript
import { EcommerceProvider } from '@payloadcms/plugin-ecommerce/client'
import { codAdapterClient } from '@wtree/payload-ecommerce-cod'

function App() {
return (
paymentMethods={[
codAdapterClient({
label: 'Cash on Delivery',
}),
]}
>
{/ Your app /}

)
}
`

Configuration Options

$3

| Option | Type | Description |
|--------|------|-------------|
| label | string | Display label for the payment method (default: "Cash on Delivery") |
| minimumOrder | number | Minimum order amount in smallest currency unit (e.g., cents) |
| maximumOrder | number | Maximum order amount in smallest currency unit |
| allowedRegions | string[] | Array of ISO 3166-1 alpha-2 country codes where COD is available |
| supportedCurrencies | string[] | Array of ISO 4217 currency codes supported for COD |
| serviceChargePercentage | number | Percentage service charge to add to orders |
| fixedServiceCharge | number | Fixed service charge in smallest currency unit |
| groupOverrides | object | Override default transaction fields |

$3

| Option | Type | Description |
|--------|------|-------------|
| label | string | Display label for the payment method (default: "Cash on Delivery") |

Transaction Fields

The COD adapter adds the following fields to transactions:

- orderID: Unique COD order identifier
- validationStatus: Order validation status (pending, validated, rejected)
- deliveryStatus: Delivery tracking (preparing, dispatched, out_for_delivery, delivered, returned)
- paymentCollected: Boolean flag for payment collection
- collectionDate: Date when payment was collected

API Endpoints

The adapter uses Payload's built-in ecommerce endpoints:

- POST /api/payments/cod/initiate - Initiate a COD order
- POST /api/payments/cod/confirm-order - Confirm and create order

Example: Complete Checkout Flow

$3

`typescript
import { useEcommerce } from '@payloadcms/plugin-ecommerce/client'

function Checkout() {
const { initiatePayment, confirmOrder } = useEcommerce()

const handleCheckout = async () => {
try {
// Step 1: Initiate COD payment
const initResult = await initiatePayment('cod', {
additionalData: {
// Additional data if needed
},
})

console.log('COD Order ID:', initResult.orderID)

// Step 2: Confirm order to complete purchase
const confirmResult = await confirmOrder('cod', {
additionalData: {
orderID: initResult.orderID,
},
})

console.log('Order confirmed:', confirmResult.orderID)
} catch (error) {
console.error('Checkout failed:', error)
}
}

return (

Complete Order (COD)

)
}
`

$3

For more control over the checkout flow, use the ecommerce hooks:

`typescript
import { useCart, useAddresses, usePayments } from '@payloadcms/plugin-ecommerce/client/react'

function AdvancedCheckout() {
const cart = useCart()
const { shippingAddress, billingAddress } = useAddresses()
const { initiatePayment, confirmOrder } = usePayments()

const handleCheckout = async () => {
try {
// Validate cart
if (!cart || !cart.items || cart.items.length === 0) {
throw new Error('Cart is empty')
}

// Validate addresses
if (!shippingAddress) {
throw new Error('Shipping address is required')
}

// Step 1: Initiate COD payment
const initResult = await initiatePayment('cod', {
cart,
shippingAddress,
billingAddress: billingAddress || shippingAddress,
})

console.log('Order initiated:', {
orderID: initResult.orderID,
serviceCharge: initResult.serviceCharge,
})

// Step 2: Confirm order
const confirmResult = await confirmOrder('cod', {
orderID: initResult.orderID,
})

console.log('Order confirmed:', {
orderID: confirmResult.orderID,
transactionID: confirmResult.transactionID,
})

// Order complete, redirect to success page
window.location.href = /order/${confirmResult.orderID}
} catch (error) {
console.error('Checkout failed:', error.message)
}
}

return (


`typescript
import { useState } from 'react'
import { useCart, usePayments } from '@payloadcms/plugin-ecommerce/client/react'

function CheckoutWithValidation() {
const cart = useCart()
const { initiatePayment, confirmOrder } = usePayments()
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)

const handleCheckout = async (formData: FormData) => {
setLoading(true)
setError(null)

try {
// Step 1: Initiate payment
const initResult = await initiatePayment('cod', {
additionalData: {
notes: formData.get('notes'),
preferredDeliveryDate: formData.get('deliveryDate'),
},
})

// Step 2: Confirm order
const confirmResult = await confirmOrder('cod', {
orderID: initResult.orderID,
})

// Success - clear cart and redirect
console.log('Order placed successfully:', confirmResult.orderID)
return confirmResult.orderID
} catch (err) {
const message = err instanceof Error ? err.message : 'Checkout failed'
setError(message)
console.error('Checkout error:', err)
} finally {
setLoading(false)
}
}

return (