Payment refunds
The payment refund object and the allowed CRUD operations on the related resource endpoint
A payment refund returns funds from a payment capture back to the customer. The transaction is processed asynchronously. Refunds can be full or partial:
A partial refund creates a new refund transaction and leaves the session in
partially_refundedstatus.A full refund happens when the total refunded amount equals the total captured amount and transitions the session to
refundedstatus.
Refund amount
A refund must reference a payment capture at creation time. The amount_cents defaults to the full remaining refund_balance_cents on the capture if not specified. The refund amount cannot exceed the capture amount.
Event-driven creation
Gateway webhook events can create a payment refund automatically if one does not already exist for the capture. This means a transaction does not need to be explicitly created via the API first — Commerce Layer will create it in response to the event, ensuring the session status and order payment status are always kept in sync regardless of whether the flow was API-initiated or event-driven.
Incoming events are matched to an existing refund by the gateway's own reference for that operation. A reference already seen updates the refund it belongs to, while a reference not seen before creates a new one.
If a refund event arrives and its corresponding payment authorization and/or payment capture are missing, behavior depends on the gateway:
Adyen — the missing authorization and capture are synthesized from the event itself. The authorization reuses the
originalReferenceAdyen supplies, but its refund notification carries no field identifying the capture's own reference, so the synthesized capture reuses the refund event's own reference as its token and the refund amount as itsamount_cents(an approximation, not the original captured amount).Stripe — the
charge.refundedevent includes the full charge object, so the missing authorization and capture are synthesized using the real Stripe charge ID and its actual authorized/captured amounts — no approximation needed.Checkout.com — like Adyen, both the missing authorization and capture are synthesized from the event itself, reusing the event's real payment ID — stable across the whole payment lifecycle — as their token. Unlike Adyen, though, the refund event carries no field for either the original authorization or capture amount, so both synthesized records reuse the refund's own amount as an approximation.
External (custom gateways) — the webhook payload must explicitly include
authorization_tokenandreference_transaction_tokenalongside the refund's owntransaction_token. If any is missing, the event is rejected outright with a422 Unprocessable Entityresponse rather than Commerce Layer guessing at a missing reference.Braintree — refund events do not cascade. A refund is only created if a
succeededpayment capture already exists for the session. Otherwise, the event is silently dropped (no refund is created, no error is raised).PayPal — refund events do not cascade. A refund is only created if a payment capture already exists for the session. Otherwise, the event is silently dropped.
Return-initiated refunds
A payment refund can be linked to a return. When a return-associated refund succeeds, the return status is updated automatically to reflect the completed refund.
Last updated