Refund API Error Codes

This page documents all error codes specific to the Refund API (v2). These errors occur when creating refunds for a previously processed payment. Each error includes the code name, HTTP status, description, recommended developer action, and example requests/responses.

---

Create Refund API — POST /refunds (v2)

Error Codes Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	MerchantTransactionId must be unique across all refund requests.	Duplicate merchantTransactionId provided.	Use a new merchantTransactionId for each refund request.
Structural Validation Errors	BAD_REQUEST	400 BAD_REQUEST	Refund already exists for the given merchantTransactionId.	A refund with the same merchantTransactionId already exists.	Do not retry with the same transaction ID; generate a new one.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	merchantTransactionId is required.	merchantTransactionId missing in the request.	Provide a valid merchantTransactionId field.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	reason is required.	reason field missing from the request.	Include reason and ensure it has a valid value.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	Invalid refund reason. reason can have only allowed values.	Provided reason is not part of the allowed enum.	Use only documented enum values for reason.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	paymentId is required.	paymentId missing from the request.	Provide a valid paymentId from a previous payment.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	payment not found.	paymentId not found or not associated with the merchant.	Use a valid paymentId from a Create Payment response.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	paymentAllocationId not linked to paymentId	refundAllocations contains IDs not belonging to the referenced payment.	Use paymentAllocationIds belonging to the correct payment.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	amount is required for each refundAllocations.	Missing amount in a refundAllocations entry.	Add an amount value to every refundAllocations entry.
Structural Validation Errors	BAD_REQUEST	400 BAD REQUEST	paymentAllocationId is required for each refundAllocations.	Missing paymentAllocationId in refundAllocations.	Provide a valid paymentAllocationId for each entry.
Structural Validation Errors	BAD_REQUEST	400 BAD_REQUEST	Zero-amount refunds not allowed.	amount = 0 submitted.	Submit only positive refund amounts.

---

Error Codes Details

Structural Validation Errors

---

DUPLICATE_TRANSACTION_ID

Details

MerchantTransactionId must be unique across all refund requests.

HTTP Status: 400
Description: A refund request was submitted using a merchantTransactionId that has already been used for a previous refund.
Resolution: Generate a unique merchantTransactionId for each refund request.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "duplicate-id-123",
  "reason": "REQUESTED_BY_CUSTOMER"
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "MerchantTransactionId must be unique across all refund requests."
}

REFUND_ALREADY_EXISTS

Details

Refund already exists for the given merchantTransactionId.

HTTP Status: 400
Description: A refund already exists for the provided merchantTransactionId.
Resolution: Do not reuse merchantTransactionId for another refund. Generate a new one.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "existing-refund-123",
  "reason": "REQUESTED_BY_CUSTOMER"
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Refund already exists for the given merchantTransactionId."
}

MISSING_MERCHANT_TRANSACTION_ID

Details

merchantTransactionId is required.

HTTP Status: 400
Description: Request omitted the required merchantTransactionId field.
Resolution: Include merchantTransactionId with a unique value.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "reason": "REQUESTED_BY_CUSTOMER"
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "merchantTransactionId is required."
}

MISSING_REFUND_REASON

Details

reason is required.

HTTP Status: 400
Description: Request did not include a reason for the refund.
Resolution: Provide reason using one of the allowed enum values.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "missing-reason"
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "reason is required."
}

INVALID_REFUND_REASON

Details

Invalid refund reason. reason can have only allowed values.

HTTP Status: 400
Description: The request included a reason that is not a valid enum value.
Resolution: Use only the supported enum values exactly as documented.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "bad-reason-1",
  "reason": "NOT_A_VALID_REASON"
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Invalid refund reason. reason can have only allowed values."
}

MISSING_PAYMENT_ID

Details

paymentId is required.

HTTP Status: 400
Description: The request did not contain paymentId.
Resolution: Provide a valid paymentId returned by the Create Payment API.

Request example

{
  "merchantTransactionId": "no-payment-id",
  "reason": "REQUESTED_BY_CUSTOMER"
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "paymentId is required."
}

PAYMENT_NOT_FOUND

Details

payment not found.

HTTP Status: 400
Description: The submitted paymentId does not exist or is not associated with the merchant.
Resolution: Use a valid paymentId from Create Payment.

Request example

{
  "paymentId": "00000000-0000-0000-0000-000000000000",
  "merchantTransactionId": "bad-payment",
  "reason": "REQUESTED_BY_CUSTOMER"
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "payment not found."
}

PAYMENT_ALLOCATION_NOT_LINKED

Details

paymentAllocationId not linked to paymentId

HTTP Status: 400
Description: refundAllocations contains a paymentAllocationId that does not belong to the specified paymentId.
Resolution: Use only paymentAllocationIds that belong to the original payment.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "alloc-not-linked",
  "reason": "REQUESTED_BY_CUSTOMER",
  "refundAllocations": [
    {
      "paymentAllocationId": "11111111-2222-3333-4444-555555555555",
      "amount": 1
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "11111111-2222-3333-4444-555555555555 not linked to 472e651e-5a1e-424d-8098-23858bf03ad7"
}

MISSING_REFUND_AMOUNT

Details

amount is required for each refundAllocations.

HTTP Status: 400
Description: An entry in refundAllocations does not contain amount.
Resolution: Provide an amount for every refundAllocations entry.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "missing-amount",
  "reason": "REQUESTED_BY_CUSTOMER",
  "refundAllocations": [
    {
      "paymentAllocationId": "14a74756-727f-4e75-a93f-f2502da27c86"
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "amount is required for each refundAllocations."
}

MISSING_PAYMENT_ALLOCATION_ID

Details

paymentAllocationId is required for each refundAllocations.

HTTP Status: 400
Description: A refundAllocations entry is missing its paymentAllocationId.
Resolution: Include paymentAllocationId for each allocation entry.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "missing-alloc-id",
  "reason": "REQUESTED_BY_CUSTOMER",
  "refundAllocations": [
    {
      "amount": 1
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "paymentAllocationId is required for each refundAllocations."
}

ZERO_AMOUNT_NOT_ALLOWED

Details

Zero-amount refunds not allowed.

HTTP Status: 400
Description: Refunds with amount = 0 are not allowed.
Resolution: Provide refund amounts greater than zero.

Request example

{
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "merchantTransactionId": "zero-amount",
  "reason": "REQUESTED_BY_CUSTOMER",
  "refundAllocations": [
    {
      "paymentAllocationId": "14a74756-727f-4e75-a93f-f2502da27c86",
      "amount": 0
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Zero-amount refunds not allowed."
}

---

Get Refund API

Error Codes Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Structural Validation Errors	NOT_FOUND	404 NOT_FOUND	Refund information not found.	refundId not found in CCG, or refundId not associated with the requesting merchant.	Use a valid refundId returned from Create Refund, and ensure the refund belongs to the requesting merchant.
Structural Validation Errors	BAD_REQUEST	400 BAD_REQUEST	RefundId is invalid.	refundId is not in valid UUID format.	Provide a valid UUID-formatted refundId.

---

Error Codes Details

Structural Validation Errors for Get Refunds

---

REFUND_NOT_FOUND

Details

Refund information not found.

HTTP Status: 404
Description: GET /refunds/refundId attempted to retrieve a refund that does not exist in CCG or is not associated with the requesting merchant.
Resolution: Use a valid refundId returned by the Create Refund response in the same environment, and ensure it belongs to the requesting merchant. If the id is incorrect or belongs to another merchant, retry with the correct merchant credentials or create a new refund.

Request example

{
"method": "GET",
"path": "/refunds/11111111-2222-3333-4444-555555555555"
}

Response example

{
"title": "NOT_FOUND",
"status": 404,
"detail": "Refund information not found."
}

INVALID_REFUND_ID

Details

RefundId is invalid.

HTTP Status: 400
Description: The refundId provided in the request path is not a valid UUID string.
Resolution: Provide a refundId in a valid UUID format. Confirm that the refundId matches the ID returned by the Create Refund response.

Request example

{
"method": "GET",
"path": "/refunds/not-a-valid-uuid"
}

Response example

{
"title": "BAD_REQUEST",
"status": 400,
"detail": "RefundId is invalid."
}