Refunds

Refunds refer to the process of returning money to a customer after a transaction has been reversed or canceled. For more information, see the Refunds Overview.

Quick Reference

• Linked Refund: Refund tied to a specific payment (requires paymentId).
• Unlinked Refund: Refund to a payment method and customer (requires paymentMethodId and customer).
• API Endpoints:
  • POST v1/refunds — Initiate a refund (linked or unlinked)
  • GET v1/refunds/{refundId} — Poll refund status
• Key Fields:
  • amount, reason, paymentId or paymentMethodId, merchantTransactionId, customer
• Common Statuses: INITIATED, COMPLETED, FAILED
• Error Codes: See Refund Error Codes

Handling Refunds

Refunds can be processed as either linked (tied to a payment) or unlinked (not tied to a specific payment, but to a payment method and customer). Merchants can initiate refunds for reasons such as duplicate transactions, customer requests, or order cancellations.

Refund Validation Flow

Most refund validations are wrapped to Stripe errors. Convenient Checkout Gateway (CCG) passes most validation responsibilities to Stripe, except for the following scenarios which are validated directly at the CCG level:

1. Invalid Payment: If the payment ID is invalid or doesn't exist, the request fails at CCG without being sent to Stripe
2. Bank Account Refund: Unlinked refund requests with a bank account payment method are rejected at CCG
3. Duplicate Transaction ID: When a refund is requested with an existing merchant transaction ID, the request is rejected at CCG

For all other validation scenarios, CCG forwards the request to Stripe and relays any validation errors from Stripe back to the client.

Merchant Options for Refunds

• Issue a full or partial refund for a payment
• Process a refund to a card payment method (unlinked)
• Track refund status via API

Refund Request with API

Refunds can be requested via the /refunds API. The API supports both linked and unlinked refunds.

Linked Refund

A linked refund is associated with a specific payment ID.

Sample linked refund request

If Amount is provided, it must be less than or equal to Transaction Amount

{
  "amount": 100,
  "reason": "DUPLICATE",
  "paymentId": "c84691be-24d0-4ed8-ae5b-578b5947eb60",
  "merchantTransactionId": "6a5215e2-30a3-470d-87ea-04df72c84e8e"
}

If Amount is not provided, the full amount of the original payment will be refunded

{
  "reason": "DUPLICATE",
  "paymentId": "c84691be-24d0-4ed8-ae5b-578b5947eb60",
  "merchantTransactionId": "6a5215e2-30a3-470d-87ea-04df72c84e8e"
}

Sample linked refund response

{
  "url": "http://api-stg.uhg.com:443/refunds/257d30aa-2ca6-4c32-ab16-3d9c572bc9b4",
  "data": {
    "id": "257d30aa-2ca6-4c32-ab16-3d9c572bc9b4",
    "paymentId": "c84691be-24d0-4ed8-ae5b-578b5947eb60",
    "merchantId": "668d9077-0574-4d5c-b30e-7f83eacba8ce",
    "reason": "DUPLICATE",
    "merchantTransactionId": "6a5215e2-30a3-470d-87ea-04df72c84e8e",
    "metadata": {
      "merchantTransactionId": "6a5215e2-30a3-470d-87ea-04df72c84e8e"
    },
    "status": "INITIATED"
  }
}

Polling Linked Refund Status

To check the status of a linked refund, use the GET v1/refunds/{refundId} endpoint.

Sample linked refund status response

{
  "url": "http://api-stg.uhg.com:443/refunds/257d30aa-2ca6-4c32-ab16-3d9c572bc9b4",
  "data": {
    "id": "257d30aa-2ca6-4c32-ab16-3d9c572bc9b4",
    "paymentId": "c84691be-24d0-4ed8-ae5b-578b5947eb60",
    "merchantId": "668d9077-0574-4d5c-b30e-7f83eacba8ce",
    "amount": 8000,
    "reason": "DUPLICATE",
    "merchantTransactionId": "6a5215e2-30a3-470d-87ea-04df72c84e8e",
    "metadata": {
      "merchantTransactionId": "6a5215e2-30a3-470d-87ea-04df72c84e8e"
    },
    "status": "COMPLETED"
  }
}

Unlinked Refund

An unlinked refund is not associated with a specific payment, but with a payment method and customer.

Sample unlinked refund request

{
  "amount": 200.0,
  "reason": "DUPLICATE",
  "paymentMethodId": "b3b6a7be-4cf8-44da-acaf-f32a1664c90f",
  "merchantTransactionId": "9b0db11e-c3d0-4f54-a805-a3c74a2ed126",
  "customer": {
    "hsid": "9c80e161-d337-4047-9baa-49178ae87571"
  }
}

Sample unlinked refund response

{
  "url": "http://api-stg.uhg.com:443/refunds/c51a5e0c-56cd-4793-b11f-4e6c22ef283e",
  "data": {
    "id": "c51a5e0c-56cd-4793-b11f-4e6c22ef283e",
    "paymentMethodId": "b3b6a7be-4cf8-44da-acaf-f32a1664c90f",
    "merchantId": "b6d8e950-3d4b-4538-b5fb-8dad40f2b7c8",
    "amount": 200,
    "reason": "DUPLICATE",
    "merchantTransactionId": "9b0db11e-c3d0-4f54-a805-a3c74a2ed126",
    "metadata": {
      "merchantTransactionId": "9b0db11e-c3d0-4f54-a805-a3c74a2ed126"
    },
    "status": "INITIATED"
  }
}

Polling Unlinked Refund Status

To check the status of an unlinked refund, use the GET v1/refunds/{refundId} endpoint.

Sample unlinked refund status response

{
  "url": "http://api-stg.uhg.com:443/refunds/c51a5e0c-56cd-4793-b11f-4e6c22ef283e",
  "data": {
    "id": "c51a5e0c-56cd-4793-b11f-4e6c22ef283e",
    "paymentMethodId": "b3b6a7be-4cf8-44da-acaf-f32a1664c90f",
    "merchantId": "b6d8e950-3d4b-4538-b5fb-8dad40f2b7c8",
    "amount": 200,
    "reason": "DUPLICATE",
    "merchantTransactionId": "9b0db11e-c3d0-4f54-a805-a3c74a2ed126",
    "metadata": {
      "merchantTransactionId": "9b0db11e-c3d0-4f54-a805-a3c74a2ed126"
    },
    "status": "COMPLETED"
  }
}

Error Handling

Refer to Refund Error Codes.