Create Refund

Create a refund to return funds to a customer.

POSThttps://api.uprails.com/refunds

Creates a new refund for a payment. You can refund the full amount or specify a partial amount. Refunds can only be created for payments with status succeeded.

Partial Refunds

You can create multiple partial refunds for a single payment. The total refunded amount cannot exceed the original payment amount.

Request Example

curl -X POST https://api.uprails.com/refunds \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -d '{
    "payment_id": "pay_abcdef1234567890",
    "amount": 500,
    "reason": "requested_by_customer",
    "metadata": {
      "order_id": "12345",
      "refund_reason": "Product returned"
    }
  }'

Request Body

payment_idstringrequired

The ID of the payment to refund

amountinteger

Amount to refund in the smallest currency unit. If not specified, refunds the full amount.

reasonstring

Reason for the refund

Enum:requested_by_customerduplicatefraudulent

metadataobject

Set of key-value pairs for storing additional information

refund_typestringdefault: instant

Type of refund to process

Enum:instantscheduled

Response

200OK

{
  "refund_id": "ref_1234567890abcdef",
  "payment_id": "pay_abcdef1234567890",
  "merchant_id": "mer_xyz789",
  "status": "pending",
  "amount": 500,
  "currency": "USD",
  "reason": "requested_by_customer",
  "metadata": {
    "order_id": "12345"
  },
  "created": "2024-01-15T14:30:00Z",
  "updated": "2024-01-15T14:30:00Z"
}

Full vs Partial Refunds

When creating a refund, you can choose to refund the full amount or a partial amount:

Full Refund

Omit the amount parameter to refund the full payment amount.

Full Refund Requestjson

{
  "payment_id": "pay_abcdef1234567890",
  "reason": "requested_by_customer"
}

Partial Refund

Specify an amount to refund only a portion of the payment.

Partial Refund Requestjson

{
  "payment_id": "pay_abcdef1234567890",
  "amount": 500,
  "reason": "requested_by_customer"
}

Best Practices

Idempotency

Use idempotency keys when creating refunds to prevent duplicate refunds if a request is retried.

Refund Limits

Your payment processor may have daily or per-transaction refund limits. Check with your processor for specific limits.