Refund reason codes

Reason codes provide integrators with detailed information about why a payment has a status requiring additional steps or has failed. Each code explains the specific condition and the recommended next action.

Declined reasons

Reason codes for the declined status ordered alphabetically.

Getpaid validates refund rules (expiration periods, maximum amounts) before submitting refund requests to the payment network. If a refund violates these rules, you'll receive a 422 - Invalid Parameters error response and the refund will not be submitted to the network.

However, if a refund or chargeback was processed through a different provider or system, the payment network may still decline a Getpaid refund request with one of the codes below (e.g., already_refunded, exceeds_captured_amount) even though Getpaid's validation passed.

Code	Description	Recommended action
already_refunded	The payment has already been fully refunded and no additional refund amount is available.	Verify the total refunded amount against the original payment. No further action possible.
declined	The refund was declined by the payment processor or issuer without a specific reason.	Contact Getpaid support to investigate the decline reason or attempt to issue the refund through alternative means if available.
exceeds_captured_amount	The requested refund amount exceeds the captured payment amount (including any previous partial refunds).	Reduce the refund amount to not exceed the remaining refundable balance of the payment.
refund_period_expired	The refund window has expired and the payment processor no longer accepts refunds for this payment.	Contact the buyer directly to arrange an alternative reimbursement method outside of the payment system.
refund_unavailable	Refunds are not available for this payment method or payment state (e.g., payment not yet captured or already disputed).	Verify the payment status. For uncaptured payments, void the authorization instead. For disputes, handle through the dispute resolution process.

Failed reasons

Reason codes for the failed status ordered alphabetically.

Code	Description	Recommended action
unavailable	The services downstream to process the request are temporarily unavailable.	Retry the operation later as any other Getpaid's server error or use a different request set up to route it through a different path (e.g., using a different payment method or a different bank account).
unexpected	There is an unexpected error for the specific request that may require further investigation from Getpaid side.	Retries usually do not change the result. The Getpaid team monitors these errors specially to detect implementation issues but you can report the issue to support@getpaid.io too.