Skip to main content
Version: v2

Refund API Error Codes

This page documents all error codes for the Refund API (v2). These errors occur when processing refunds for payments. Each error includes the code name, HTTP status, description, recommended developer action, and notes where applicable.

Error Summary​

Authorization error​

Error TitleHTTP StatusError Message
FORBIDDEN403403 FORBIDDEN. RequestId: ${x-request-id}

Resource Not Found error​

Error TitleHTTP StatusError Message
NOT_FOUND404refundId not found

Schema validation error​

Error TitleHTTP StatusError Message
INVALID_REQUEST400source header cannot exceed 50 characters
INVALID_REQUEST400paymentId is required
INVALID_REQUEST400reason should match any one of allowed values: DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER
INVALID_REQUEST400merchantTransactionId is required
INVALID_REQUEST400merchantTransactionId cannot exceed 50 characters
INVALID_REQUEST400metadata cannot exceed 20 entries
INVALID_REQUEST400metadata key cannot exceed 40 characters
INVALID_REQUEST400metadata value cannot exceed 100 characters
INVALID_REQUEST400refundAllocations[n].paymentAllocationId must be valid UUID
INVALID_REQUEST400(added: feature parity) refundAllocations[0].paymentMethodId must be valid UUID
INVALID_REQUEST400agent.firstName cannot exceed 50 characters
INVALID_REQUEST400agent.lastName cannot exceed 50 characters
INVALID_REQUEST400agent.userId cannot exceed 50 characters
INVALID_REQUEST400agent.userId is required
INVALID_REQUEST400refundId must be valid UUID
INVALID_REQUEST400(added: feature parity) customer.firstName cannot exceed 50 characters
INVALID_REQUEST400(added: feature parity) customer.lastName cannot exceed 50 characters
INVALID_REQUEST400(added: feature parity) customer.email must be a valid email address
INVALID_REQUEST400(added: feature parity) customer.email cannot exceed 120 characters
INVALID_REQUEST400(added: feature parity) customer.ssn must contain only digits and cannot exceed 4 characters
INVALID_REQUEST400(added: feature parity) customer.dateOfBirth must be a valid date in format YYYY-MM-DD
INVALID_REQUEST400(added: feature parity) customer.zip5 must be exactly 5 digits
INVALID_REQUEST400(added: feature parity) customer.phoneNumber.countryCode must contain only digits and must be 1 to 3 characters long
INVALID_REQUEST400(added: feature parity) customer.phoneNumber.number must contain only digits and must be 4-11 characters long
INVALID_REQUEST400(added: feature parity) customer.enterpriseIdentifier must contain only digits
INVALID_REQUEST400(added: feature parity) customer.hsid must be a valid UUID

Business rule violation error​

Error TitleHTTP StatusError Message
UNPROCESSABLE_ENTITY422(added: feature parity) paymentId or refundAllocations[0].paymentMethodId is required
UNPROCESSABLE_ENTITY422(added: feature parity) Either paymentId or refundAllocations[0].paymentMethodId should be provided. The request has both paymentId and refundAllocations[0].paymentMethodId
UNPROCESSABLE_ENTITY422paymentId not found
UNPROCESSABLE_ENTITY422(added: feature parity) refundAllocations[0].paymentMethodId not found
UNPROCESSABLE_ENTITY422(added: feature parity) Credit is not allowed for bank accounts
UNPROCESSABLE_ENTITY422(updated: feature parity) Maximum number of refundAllocations allowed is 2
UNPROCESSABLE_ENTITY422(added: feature parity) Maximum number of refundAllocations allowed is 1
UNPROCESSABLE_ENTITY422(updated: feature parity) Invalid refundAllocations[n].amount: ${amount}. The value must be an integer ≥ 1
UNPROCESSABLE_ENTITY422(added: feature parity) Invalid refundAllocations[n].amount: ${amount}, it must be between 1 and 99999999 and not contain decimals
UNPROCESSABLE_ENTITY422(updated: feature parity) refundAllocations[n].amount is required
UNPROCESSABLE_ENTITY422(updated: feature parity) refundAllocations[n].paymentAllocationId is required
UNPROCESSABLE_ENTITY422A refund with this merchantTransactionId already exists. Use new merchantTransactionId
UNPROCESSABLE_ENTITY422refundAllocations[n].paymentAllocationId must be associated with the specified paymentId
UNPROCESSABLE_ENTITY422refundAllocations[].paymentAllocationId must be unique
UNPROCESSABLE_ENTITY422Refund is only permitted for a payment in COMPLETED status
UNPROCESSABLE_ENTITY422(added: feature parity) When refundAllocations[0].paymentMethodId is present, customer object must include at least one of customer.hsid, customer.enterpriseId, or customer.metadata

Refund Payment processor error​

RefundAllocation Payment processor error​

Error TitleHTTP StatusError Message
REFUND_ERRORNAThis payment is already refunded
REFUND_ERRORNAThis payment is too old to be refunded
REFUND_ERRORNARefund amount cannot be more than the un-refunded amount of the original payment
REFUND_ERRORNARefund amount cannot be more than the payment amount
REFUND_ERRORNACannot issue refund for this payment
REFUND_ERRORNAPayment method is canceled by a customer or expired by the financial partner
REFUND_ERRORNAA previous attempt to refund this payment has failed
REFUND_ERRORNAThe amount given exceeds the allowed refund limit
REFUND_ERRORNAPayment is in dispute and not available for refund
REFUND_ERRORNARefund declined by financial partner
REFUND_ERRORNARefund is pending due to insufficient funds and pending refund expiry window is closed
REFUND_ERRORNARefund has failed due to loss or theft of the original card
REFUND_ERRORNARefund failed upon the business's request
REFUND_ERRORNARefund has failed due to an unknown reason

Error Details​

Authorization error​

Resource Not Found error​

Schema validation error​

Business rule violation error​

Refund Payment processor error​

RefundAllocation Payment processor error​

Contains detailed error information explaining why a specific refundAllocation failed to process.

tip
HTTP Status Codes
  • For refundAllocation-level entries, the HTTP status is shown as NA, as it is inherited from the parent 422 UNPROCESSABLE_ENTITY response.
  • refundAllocation level errors are returned under refundAllocations[n].error.