Skip to Content

Refund a payment

POST/payments/{id}/refund

Refund a two-step payment, returning funds to the customer's wallet. Only valid for payments created with payment_method: two_step. Requires a signed request (signRefund()); the destination address is part of the signature and is screened before funds move.

Headers

HeaderDescriptionRequired
AuthorizationBearer token with your secret API keyyes

Path Parameters

NameTypeRequiredDescription
idstringyes

Request Body

FieldTypeRequiredDescription
destinationstringyes
deadlineintegeryes

Example Request

Request

const response = await fetch('https://checkout-api.exodus.com/payments/<id>/refund', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "destination": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
    "deadline": 1798761600
  }),
});

Responses

StatusDescription
200The refunded payment.
400Validation error
401Missing or invalid authentication
403API key lacks the required scope
404Resource not found
504code: tx_pending: the transaction was broadcast but the relay could not read its receipt within the wait (the wait timed out, or the RPC failed while polling). data carries payment_id and tx_hash. Retry the same request after the transaction confirms to record the result; a retry after the signed deadline needs a fresh signature. The retry returns the payment with tx_hash: null, so keep the hash from this response. If the transaction reverts or never mines instead, nothing is recorded and the payment stays escrow_confirmed, so you can send the same request again (with a fresh signature after the signed deadline).

Response body

FieldTypeRequiredDescription
idstringyes
objectenum: paymentyes
statusenum: client_deposit_pending | client_deposit_detected | client_deposit_confirmed | client_deposit_expired | escrow_confirmed | settlement_pending | settled | failed | refunded | cancelledyes
payment_methodenum: direct | two_stepyes
detected_assetstring | nullyes
detected_token_symbolstring | nullyes
detected_chainstring | nullyes
token_amountstring | nullyes
token_amount_decimalstring | nullyes
deposit_addressstring | nullyes
payer_addressesstring[]yes
on_chain_idstring | nullyes
factory_addressstring | nullyes
payment_optionsobject[]yes
created_atstring · date-timeyes
flaggedbooleanyes

payment_options

FieldTypeRequiredDescription
on_chain_idstringyes
deposit_addressstringyes
chain_familystringyes
tokenstring | nullyes

Example Response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "object": "payment",
  "status": "settled",
  "payment_method": "two_step",
  "detected_asset": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "detected_token_symbol": "USDC",
  "detected_chain": "eip155:1",
  "token_amount": "50000000",
  "token_amount_decimal": "50",
  "deposit_address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
  "payer_addresses": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21"
  ],
  "on_chain_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "factory_address": "0x2f1c4e7b9a3d5c8e6f0a1b2c3d4e5f6a7b8c9d0e",
  "payment_options": [
    {
      "on_chain_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
      "deposit_address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
      "chain_family": "evm",
      "token": "USDC"
    }
  ],
  "created_at": "2024-01-15T12:30:00Z",
  "flagged": false
}

Error Response

Error (e.g. 400)

{
  "error": {
    "type": "validation_error",
    "message": "amount must be a positive number",
    "param": "amount"
  }
}
Last updated on

Start building

XO

Request Demo

Schedule a call with our team

Select a productArrow right

Start building
Grateful

Contact Us

We're here to help