Refunds — EPD Commerce

What you’ll do

Reverse part or all of a previously-paid order. Funds typically settle back to the cardholder within 5–10 business days, depending on the issuing bank.

Use this recipe for: customer-service refunds, accidental duplicate charges, returned goods.

Endpoint

Refunds are a sub-resource of an order (not a transaction):

POST /v1/orders/:id/refund

Full refund

Send no amount to refund everything captured on the order:

curl -X POST https://api.epd.com/v1/orders/$ORDER_ID/refund \
  -H "Authorization: Bearer $EPD_KEY" \
  -H "epd-version: 2026-02-11" \
  -H "X-EPD-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Partial refund

Pass an amount smaller than the order total. The remainder stays captured. You can issue multiple partial refunds up to the original total.

curl -X POST https://api.epd.com/v1/orders/$ORDER_ID/refund \
  -H "Authorization: Bearer $EPD_KEY" \
  -H "epd-version: 2026-02-11" \
  -H "X-EPD-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

You cannot refund more than the original captured amount, even across multiple partial refunds. The API returns validation_error with field_errors[].code = invalid_value.

Confirming a refund

The synchronous response confirms EPD accepted the request. The downstream gateway/processor settles the refund asynchronously — listen for order.refunded (full) or order.partially_refunded (partial) before notifying the customer. If the processor rejects the refund, you’ll get order.refund_failed instead.

Always use a fresh X-EPD-Idempotency-Key per refund attempt. Re-sending the same key returns the original refund (which is what you want on a network retry) but a new refund needs a new key.

Common errors

Error code	Status	Why
`resource_not_found`	404	Order id does not exist or belongs to another merchant.
`invalid_state_transition`	422	Order is not in a refundable state (e.g. already fully refunded).
`validation_error`	400	Refund amount exceeds the remaining refundable balance.
`gateway_error`	502	Downstream processor temporarily failed; safe to retry.