Refund a Payment

POST /v1/payments/refund

Refunds a captured payment, either fully or partially. Only PaymentIntents with status succeeded can be refunded.

Request Parameters

Parameter	Type	Required	Description
`payment_intent_id`	string (UUID)	Yes	The ID of the captured PaymentIntent to refund.
`amount`	integer	No	Amount to refund in cents. Set to `0` or omit for a full refund.
`reason`	string	No	Reason for the refund (e.g., `customer_request`, `duplicate`, `fraudulent`).

Examples

Full Refund

Partial Refund

To refund a specific amount, set amount to the desired value in cents:


curl -X POST https://sandbox.api.gatelithix.com/v1/payments/refund \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ref_$(uuidgen)" \
  -d '{
    "payment_intent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 1500
  }'

Multiple partial refunds can be issued against the same PaymentIntent until the total refunded amount equals the original amount.

Response


{
  "id": "r1234567-89ab-cdef-0123-456789abcdef",
  "payment_intent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": 5000,
  "status": "succeeded",
  "reason": "customer_request",
  "test_mode": true,
  "created_at": "2026-03-18T12:05:00Z"
}

Error Cases

Error Code	HTTP Status	Cause
`invalid_param`	400	Missing payment_intent_id
`refund_exceeds_amount`	400	Refund amount exceeds remaining balance
`payment_intent_not_found`	404	PaymentIntent does not exist
`invalid_state_transition`	409	PaymentIntent is not in `succeeded` status