Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.smartretry.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

A refund returns funds to the customer’s payment instrument for a previously completed sale or capture. You can issue a full refund or a partial refund by specifying an amount.
Safe retries for this POST endpoint use the Idempotency-Key header. Reuse the same key only when retrying the exact same request body. See Idempotency.
curl --request POST \
  --url https://api.smartretry.com/v1/payments/refund/ABC123 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: refund-20260331-001' \
  --data '{
    "transaction_reference_id": "TX8A3F2C",
    "order_reference_id": "OR7B9E1D",
    "merchant_transaction_id": "refund-20260331-001",
    "amount": 25.00
  }'

{
  "transaction_id": "TX2E6G8H",
  "order_id": "OR7B9E1D",
  "merchant_transaction_id": "refund-20260331-001",
  "accepted": true
}

​
Path parameters

​
terminal_friendly_id
string
required
Your terminal identifier. Exactly 6 characters.

​
Request body

​
transaction_reference_id
string
required
The transaction_id of the sale or capture you want to refund. Exactly 8 characters.
​
order_reference_id
string
required
The order_id associated with the transaction you want to refund. Exactly 8 characters.
​
merchant_transaction_id
string
Your unique identifier for this refund transaction. Must be different from the merchant_transaction_id of the original transaction.
​
amount
number
Amount to refund in major currency units (e.g., 25.00 for $25.00). If omitted, the full transaction amount is refunded. Partial refunds are supported - you can issue multiple partial refunds as long as the total does not exceed the original transaction amount.
​
currency
string
Three-letter ISO 4217 currency code. If omitted, the currency of the original transaction is used.

​
Response

​
transaction_id
string
required
SmartRetry’s unique identifier for this refund transaction. Exactly 8 characters.
​
order_id
string
required
The order identifier, matching the order_id from the original transaction.
​
merchant_transaction_id
string
required
The merchant_transaction_id you provided in the request, echoed back for confirmation.
​
accepted
boolean
required
true if the refund was accepted for processing. Poll the status endpoint using the returned transaction_id to confirm the refund outcome.
To refund only part of a transaction, provide an amount less than the original transaction total. You can issue multiple partial refunds against the same transaction.
You cannot refund a pre-authorization that has not yet been captured. Use the void endpoint to cancel a pre-authorization before capture.