Version: v2

Refund Error Codes

This document provides a comprehensive reference for refund-related errors in the Convenient Checkout API. These errors help identify issues with refund requests and guide you in resolving them.

Quick Reference to Related Error Codes

For Payment object validation errors, see the Payment Object Error Codes

Error Codes Summary

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Refund Amount Validation	INVALID_REQUEST	`400 BAD REQUEST`	Refund amount cannot be more than the un-refunded amount of the original payment	When attempting to refund more than the available amount	Ensure refund amount is less than or equal to the available (un-refunded) amount
	INVALID_REQUEST	`400 BAD REQUEST`	When paymentMethodId is present, amount is required	When using paymentMethodId without specifying an amount	Include a valid amount when using paymentMethodId
Payment Status Validation	PAYMENT_ERROR	`400 BAD REQUEST`	Cannot issue refund for this payment	When attempting to refund a payment not in COMPLETED status	Only attempt to refund payments that are in COMPLETED status
Payment Status Validation	INVALID_REQUEST	`400 BAD REQUEST`	Cannot issue refund for this payment	When attempting to refund for disputed fraudulent transaction	Disputed fraudulent transactions cannot be refunded
	INVALID_REQUEST	`400 BAD REQUEST`	Refunds can only be processed for captured payments	When attempting to refund a payment in AUTHORIZED status	Capture the payment before attempting to refund it or cancel the payment if not required.
	INVALID_REQUEST	`400 BAD REQUEST`	The amount given exceeds the allowed refund limit	When attempting to issue Credit beyond allowed refund limit	Reduce the refund amount to be within the allowed limit
Payment Identifier Validation	INVALID_REQUEST	`400 BAD REQUEST`	paymentId or paymentMethodId is required	When neither paymentId nor paymentMethodId is provided	Include either paymentId or paymentMethodId in the request
	INVALID_REQUEST	`400 BAD REQUEST`	Either paymentId or paymentMethodId should be provided. The request has both paymentId and paymentMethodId	When both paymentId and paymentMethodId are provided	Use either paymentId or paymentMethodId, not both
	INVALID_REQUEST	`400 BAD REQUEST`	When paymentMethodId is present, customer should contain hsid, enterpriseId or metadata	When customer identifiers are missing with paymentMethodId	Include customer identifiers when using paymentMethodId
Payment Method Status Validation	INVALID_REQUEST	`400 BAD REQUEST`	Payment method is canceled by a customer or expired by the financial partner	When attempting to refund using an invalid payment method	Use only valid, active payment methods for refunds
	INVALID_REQUEST	`400 BAD REQUEST`	Credit is not allowed for bank accounts.	When attempting to refund to a bank account payment method	Use card payment methods for unlinked refunds/credits
	INVALID_REQUEST	`400 BAD REQUEST`	Invalid paymentMethodId	When attempting to issue Credit for Invalid or Deleted Payment Method	Use only valid, active payment methods for refunds
Payment Dispute Validation	INVALID_REQUEST	`400 BAD REQUEST`	Payment is in dispute and not available for refund	When attempting to refund a payment that is in dispute	Refunds are not applicable for payments where the merchant has lost the dispute, as the customer has already received the funds through the dispute resolution process.
Refund Already Exists	INVALID_REQUEST	`400 BAD REQUEST`	This payment is already refunded	When attempting to create a refund on already completed payment	If the payment has already been fully refunded, additional linked refunds are not allowed. To provide more funds to the customer, issue a credit using a valid payment method.
Refund Already Exists (merchantTransactionId)	INVALID_REQUEST	`400 BAD REQUEST`	Refund already exists for the given merchantTransactionId	When attempting to create a refund with a duplicate merchantTransactionId	Provide a unique merchantTransactionId for every refund transaction

Error Codes Details

Refund Amount Validation

Refund amount cannot be more than the un-refunded amount of the original payment

Refund Type: Linked Refund

Scenario: Refunds cannot exceed the original payment amount. For instance, if $50 is refunded from a $100 payment, any subsequent refund should not exceed $50.

Sample Request:

{
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 5000,
  "merchantRefundId": "refund-123"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Refund amount cannot be more than the un-refunded amount of the original payment"
}

Sample Webhook Response:

caution

Code missing inside error object in Refund Webhook Response

{
  "name": "REFUND_FAILED",
  "source": "",
  "payload": {
    // refund webhook payload
   "refundId": "11f3878d-5615-44fc-b297-3e96cf582c31",
    "payment": {
      // payment details
    },
    "paymentMethod": {
      // payment method details
    },
    "customer": {
      // customer details
    },
    "error": {
      "description": "Refund amount cannot be more than the payment amount"
    }
  }
}

When paymentMethodId is present, amount is required

Refund Type: Unlinked Refund

Scenario: When initiating a refund using a payment method ID, you must specify the refund amount.

Sample Request:

{
  
  "reason": "DUPLICATE",
  "paymentMethodId": "89a2a596-0c46-406d-9782-a5229778dd6e",
  "merchantTransactionId": "dcf20e68-9a80-42fa-a9a5-e46c62fd047c",
  "customer": {
    "hsid": "14d52a64-cde0-4d11-8e3d-371a32bf53ae"
  }
  // amount is missing
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "When paymentMethodId is present, amount is required"
}

Sample Webhook Response:

note

Validation failures in the Post Refunds API do not result in webhook triggers

Payment Status Validation

Cannot issue refund for this payment

Refund Type: Linked Refund

Scenario:

Refund can only be initiated for the payments in COMPLETED status
Refund initiated for disputed payments
Refund initiated with invalid payment id

When Refund is initiated for Failed or Invalid Payment id

Sample Request:

{
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 1000,
  "merchantRefundId": "refund-123"
}

Sample Error Response:

{
  "title": "PAYMENT_ERROR",
  "status": 400,
  "detail": "Cannot issue refund for this payment"
}

Sample Webhook Response:

{
  "name": "REFUND_FAILED",
  "source": "",
  "payload": {
    // refund webhook payload
    "refundId": "11f3878d-5615-44fc-b297-3e96cf582c31",
    "paymentMethod": {
      // payment method details
    },
    "customer": {
      // customer details
    },
    "error": {
      "code": "PAYMENT_ERROR",
      "description": "Cannot issue refund for this payment"
    }
  }
}

When Refund is initiated for Disputed fraudulent transaction

Sample Request:

{
  "amount" : 100,
  "reason" : "DUPLICATE",
  "paymentId" : "8bb8da97-a99c-4019-9154-4ee851b340b2",
  "merchantTransactionId" : "60c673d7-39c5-40df-b8de-16793b35d7e5"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Cannot issue refund for this payment"
}

Sample Webhook Response:

caution

Title inside refund response and the code inside the error object in the webhook response are inconsistent.....

{
  "name": "REFUND_FAILED",
  "source": "card-refund",
  "payload": {
    // refund webhook payload
    "refundId": "9ec59c5a-865c-456d-a21f-0735178629a0",
    "payment": {
      // payment details
    },
    "paymentMethod": {
      // payment method details
    },
    "customer": {
      // customer details
    },
    "error": {
      "code": "charge_disputed",
      "description": "Cannot issue refund for this payment"
    }
  }
}

Refunds can only be processed for captured payments

Refund Type: Linked Refund

Scenario: Refunds are not applicable for payments in AUTHORIZED status

Sample Request:

{
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 1000,
  "merchantRefundId": "refund-123"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Refunds can only be processed for captured payments"
}

Sample Error Response:

caution

Code missing inside error object in Refund Webhook Response

{
  "name": "REFUND_FAILED",
  "source": "vendor-portal",
  "payload": {
    // refund webhook payload
    "refundId": "d8765a0b-db66-420c-9785-d6caa99c055b",
    // refund webhook payload
    "payment": {
      // payment details
    },
    "paymentMethod": {
      // payment method details
    },
    "customer": {
      // customer details
    },
    "error": {
      "description": "Refunds can only be processed for captured payments"
    }
  }
}

The amount given exceeds the allowed refund limit

Refund Type: Unlinked Refund

Scenario: Credit will not be issued if amount exceeds the allowed refund limit.

Sample Request:

{
  "amount" : 44444444,
  "reason" : "DUPLICATE",
  "paymentMethodId" : "f85fdc1b-41af-4cd6-9272-13fb3e5009e2",
  "paymentId" : null,
  "merchantTransactionId" : "cb94a178-a51c-4bae-8ae2-841745424915",
  "customer" : {
    "hsid" : "6c7173ea-bf7e-42e8-a320-c413e7863107"
  }
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "The amount given exceeds the allowed refund limit"
}

Sample Webhook Response:

caution

Title inside refund response and the code inside the error object in the webhook response are inconsistent.....

{
  "name": "REFUND_FAILED",
  "source": "",
  "payload": {
    // refund webhook payload
    "refundId": "6b7389c1-401d-447a-b407-cd4bb4a12882",
    "paymentMethod": {
      // payment method details
    },
    "customer": {
      // customer details
    },
    "error": {
      "code": "amount_too_large",
      "description": "The amount given exceeds the allowed refund limit"
    }
  }
}

Payment Identifier Validation

paymentId or paymentMethodId is required

Refund Type: Linked/UnLinked Refund

Scenario: Either the Payment ID or Payment Method ID is required to initiate a refund

Sample Request:

{
  "amount": 1000,
  "merchantRefundId": "refund-123"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentId or paymentMethodId is required"
}

Sample Webhook Response:

note

Validation failures in the Post Refunds API do not result in webhook triggers

Either paymentId or paymentMethodId should be provided

Refund Type: Linked/UnLinked Refund

Scenario: Both the Payment ID and Payment Method ID should not be provided when initiating a refund

Sample Request:

{
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "paymentMethodId": "pm_123e4567e89b12d3a456426614174000",
  "amount": 1000,
  "merchantRefundId": "refund-123"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Either paymentId or paymentMethodId should be provided. The request has both paymentId and paymentMethodId"
}

Sample Webhook Response:

note

Validation failures in the Post Refunds API do not result in webhook triggers

Customer identifier required with paymentMethodId

Refund Type: UnLinked Refund

Scenario: When using paymentMethodId for refunds, customer identification (hsid, enterpriseId, or metadata) must be provided

Sample Request:

{
  "paymentMethodId": "pm_123e4567e89b12d3a456426614174000",
  "amount": 1000,
  "customer": {}
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "When paymentMethodId is present, customer should contain hsid, enterpriseId or metadata"
}

Sample Webhook Response:

note

Validation failures in the Post Refunds API do not result in webhook triggers

Payment Method Status Validation

Payment method is canceled or expired

Refund Type: Linked Refund

Scenario: Refunds cannot be processed for expired or invalid payment methods

Sample Request:

{
  "paymentMethodId": "pm_123e4567e89b12d3a456426614174000",
  "amount": 1000,
  "merchantRefundId": "refund-123"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Payment method is canceled by a customer or expired by the financial partner"
}

Sample Webhook Response:

caution

Title inside refund response and the code inside the error object in the webhook response are inconsistent.....

{
  "name": "REFUND_FAILED",
  "source": "",
  "payload": {
    "refundId": "ae154ee8-f181-47cc-959d-7dea40be6d96",
    // refund webhook payload
    "payment": {
      // payment details
    },
    "paymentMethod": {
      // payment method details
    },
    "customer": {
      // customer details
    },
    "error": {
      "code": "VENDOR_ERROR",
      "description": "Payment method is canceled by a customer or expired by the financial partner"
    }
   
  }
}

Credit not allowed for bank accounts

Refund Type: UnLinked Refund

Scenario: Refunds cannot be processed for bank account payment methods due to card type restrictions

Sample Request:

{
  "paymentMethodId": "pm_bank_account_123e4567",
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "amount": 1000
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Credit is not allowed for bank accounts."
}

Sample Webhook Response:

caution

Customer and Payment Method Object missing inside Webhook Response

{
  "name": "REFUND_FAILED",
  "source": "",
  "payload": {
    // refund webhook payload
    "refundId": "f9005866-6c00-4a95-a881-070668b6e4ee",
    "error": {
      "code": "INVALID_REQUEST",
      "description": "Credit is not allowed for bank accounts."
    }
  }
}

Invalid Payment Method Id

Refund Type: UnLinked Refund

Scenario: Credit should not be issued if payment method is not valid or it is no longer attached to customer.

Sample Request:

{
  "amount" : 400.0,
  "reason" : "DUPLICATE",
  "paymentMethodId" : "5b5d379c-2dfa-4c13-af24-51dd91c02526",
  "merchantTransactionId" : "e42c2c6d-53b8-411c-b103-b2dfa9411989",
  "customer" : {
    "hsid" : "6fd7b1fa-8a5b-4d71-9437-3e812325ac5d"
  }
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Invalid paymentMethodId"
}

Sample Webhook Response:

caution

Customer and Payment Method Object missing inside Webhook Response

{
  "name": "REFUND_FAILED",
  "source": "vendor-portal",
  "payload": {
    // refund webhook payload
    "refundId": "465f1327-73fe-4c04-9635-8a65bf578336",
    "error": {
      "code": "INVALID_REQUEST",
      "description": "Invalid paymentMethodId"
    }
   
  }
}

Payment Dispute Validation

Payment is in dispute

Refund Type: Linked Refund

Scenario: Payments that are in dispute cannot be refunded

Sample Request:

{
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 1000,
  "merchantRefundId": "refund-123"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Payment is in dispute and not available for refund"
}

Sample Webhook Response:

caution

Title inside refund response and the code inside the error object in the webhook response are inconsistent.....

{
  "name": "REFUND_FAILED",
  "source": "",
  "payload": {
    // refund webhook payload
    "refundId": "8d7ecc61-8389-4d9b-a8a6-fe1ec05127cb",
    "payment": {
  // payment details
    },
    "paymentMethod": {
  // payment method details
    },
    "customer": {
  // customer details
    },
    "error": {
      "code": "VENDOR_ERROR",
      "description": "Payment is in dispute and not available for refund"
    }
    
  }
}

Refund Already Exists

This payment is already refunded

Refund Type: Linked/Unlinked Refund

Scenario: A refund with the same merchantTransactionId has already been processed. Duplicate refunds are not allowed for the same merchantTransactionId.

Sample Request:

{
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 1000,
  "merchantTransactionId": "cb94a178-a51c-4bae-8ae2-841745424915"
}

Sample Error Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "This payment is already refunded"
}

Sample Webhook Response:

caution

Title inside refund response and the code inside the error object in the webhook response are inconsistent.....

{
  "name": "REFUND_FAILED",
  "source": "",
  "payload": {
    // refund webhook payload
    "refundId": "6c53af2f-3705-4353-86da-4aeea10ba176",
    "payment": {
  // payment details
    },
    "paymentMethod": {
  // payment method details
    },
    "customer": {
  // customer details
    },
    "error": {
      "code": "charge_already_refunded",
      "description": "This payment is already refunded"
    }
  }
}

For more detailed information about the Refund Webhook structure, refer Refund Webhook

Error Codes Summary​

Error Codes Details​

Refund Amount Validation​

Payment Status Validation​

Payment Identifier Validation​

Payment Method Status Validation​

Payment Dispute Validation​

Refund Already Exists​

Error Codes Summary

Error Codes Details

Refund Amount Validation

Payment Status Validation

Payment Identifier Validation

Payment Method Status Validation

Payment Dispute Validation

Refund Already Exists