Create Refund

POST/refunds

Description

Create a refund for a completed stablecoin payment. The refund is processed as an on-chain transaction to the customer’s original wallet address. You can refund the full amount or specify a partial amount.

⚠️

You can only refund payments that have been successfully completed and confirmed on-chain. Partial refunds are allowed up to the original payment amount.

Headers

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

Request Body

Name	Type	Description	Required
payment_id	string	The ID of the payment to refund.	yes
amount	number	Amount to refund in smallest currency unit. If omitted, refunds the full amount.	no
reason	string	Reason for the refund: "duplicate", "fraudulent", or "requested_by_customer".	no
metadata	object	Custom key-value pairs to attach to the refund.	no

Example Request

Full Refund

const response = await fetch('https://checkout.exodus.com/refunds', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payment_id: 'pay_0987654321fedcba',
    reason: 'requested_by_customer',
  }),
});

Partial Refund

const response = await fetch('https://checkout.exodus.com/refunds', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payment_id: 'pay_0987654321fedcba',
    amount: 2500, // Refund $25.00 of a $50.00 payment
    reason: 'requested_by_customer',
    metadata: {
      refund_ticket: 'TICKET-12345',
    },
  }),
});

Response

SUCCESSFUL REFUND CREATION

{
  "id": "ref_1234567890abcdef",
  "object": "refund",
  "payment_id": "pay_0987654321fedcba",
  "amount": 5000,
  "currency": "USD",
  "status": "pending",
  "reason": "requested_by_customer",
  "stablecoin": "USDC",
  "network": "ethereum",
  "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
  "metadata": {},
  "created_at": "2024-01-20T15:30:00Z"
}

Error Responses

PAYMENT NOT REFUNDABLE

{
  "error": {
    "type": "invalid_request",
    "message": "Payment cannot be refunded. It may not be completed or already fully refunded."
  }
}

AMOUNT EXCEEDS AVAILABLE

{
  "error": {
    "type": "validation_error",
    "message": "Refund amount exceeds the amount available for refund",
    "param": "amount"
  }
}