Refund Payment

Issue full or partial refunds for completed payments

POST/v1/payments/:id/refund

Full and Partial Refunds

You can refund the full amount or a partial amount. Multiple partial refunds are allowed up to the original payment amount. Refunds can only be issued on payments with status succeeded or partially_refunded.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API secret key
Content-Type	Yes	application/json

Path Parameters

Parameter	Type	Description
id	string	The payment ID to refund (e.g., `pay_abc123xyz`)

Request Body

Field	Type	Required	Description
amount	integer?	No	Amount to refund in cents. Omit for full refund
reason	string?	No	`customer_requested`, `duplicate`, `fraudulent`, or custom string
metadata	object?	No	Additional metadata to attach to the refund

Refund Timing

Refund timing depends on the original payment method:

Payment Method	Refund Initiated	Customer Receives Funds
Credit Card	Instant	5-10 business days
Debit Card	Instant	3-5 business days
ACH	Next business day	5-7 business days

Note: Refund timing is determined by the customer's bank or card issuer. The times above are estimates. Hedge Payments initiates the refund immediately, but the customer's financial institution controls the final deposit.

Response

Full Refund

{
  "id": "pay_abc123xyz",
  "object": "payment",
  "amount": 9999,
  "currency": "USD",
  "status": "refunded",
  "refunded_amount": 9999,
  "refunds": [
    {
      "id": "ref_xyz789",
      "amount": 9999,
      "reason": "customer_requested",
      "status": "succeeded",
      "created_at": "2024-06-16T14:00:00Z"
    }
  ],
  "created_at": "2024-06-15T10:30:00Z",
  "updated_at": "2024-06-16T14:00:00Z"
}

Partial Refund

{
  "id": "pay_abc123xyz",
  "object": "payment",
  "amount": 9999,
  "currency": "USD",
  "status": "partially_refunded",
  "refunded_amount": 2500,
  "refunds": [
    {
      "id": "ref_xyz789",
      "amount": 2500,
      "reason": "customer_requested",
      "status": "succeeded",
      "created_at": "2024-06-16T14:00:00Z"
    }
  ],
  "created_at": "2024-06-15T10:30:00Z",
  "updated_at": "2024-06-16T14:00:00Z"
}

Code Examples

Node.js - Full Refund

import { HedgePayments } from '@hedgepayments/node'

const hedge = new HedgePayments({
  apiKey: process.env.HEDGE_API_KEY,
  apiSecret: process.env.HEDGE_API_SECRET
})

// Full refund (omit amount)
const payment = await hedge.payments.refund('pay_abc123xyz', {
  reason: 'customer_requested'
})

console.log('Refund status:', payment.status) // 'refunded'
console.log('Refunded amount:', payment.refunded_amount / 100)

Node.js - Partial Refund

// Partial refund ($25.00 of a $99.99 payment)
const payment = await hedge.payments.refund('pay_abc123xyz', {
  amount: 2500,
  reason: 'customer_requested',
  metadata: {
    refund_item: 'shipping_fee'
  }
})

console.log('Status:', payment.status) // 'partially_refunded'
console.log('Refunded so far:', payment.refunded_amount / 100) // 25.00
console.log('Remaining refundable:', (payment.amount - payment.refunded_amount) / 100) // 74.99

cURL - Full Refund

curl -X POST https://api.hedgepayments.com/v1/payments/pay_abc123xyz/refund \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "customer_requested"
  }'

cURL - Partial Refund

curl -X POST https://api.hedgepayments.com/v1/payments/pay_abc123xyz/refund \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "reason": "customer_requested"
  }'

Error Responses

Code	Error	Description
401	unauthorized	Invalid or missing API key
404	not_found	Payment not found with the given ID
412	payment_not_refundable	Payment status does not allow refunds
422	refund_amount_exceeded	Refund amount exceeds the remaining refundable amount

// 422 error example
{
  "error": {
    "code": "refund_amount_exceeded",
    "message": "Refund amount exceeds the remaining refundable amount.",
    "details": {
      "payment_id": "pay_abc123xyz",
      "original_amount": 9999,
      "already_refunded": 7500,
      "remaining_refundable": 2499,
      "requested_refund": 5000
    }
  }
}