SETSimple Easy Transactions
SET DocsAPI reference and complianceUpdated 2026-11-09
Browse: SET Merchant API

SET Merchant API · Refunds

Refund a bank or stablecoin payment

POST/v1/refunds

Key scope: write · Success: 201

Sends money back to a payer: a payout from the merchant's own custodial wallet to the payer, tied to the deposit, Cash-Out payment or Conversion payment it returns. Name the payer first as a recipient (POST /v1/recipients). It runs POST /v1/payouts with every check (balance, fee, Travel Rule with the payer as beneficiary). Card payments are refunded with POST /v1/card_payments/{id}/refunds.

Headers

Idempotency-Key string
Optional. The same key and body run once; a replay answers with Idempotent-Replayed: true. Kept 24 hours.

Body

payment stringrequired
One of your deposits, Cash-Out payments or Conversion payments.
wallet stringrequired
Your wallet that pays the refund.
recipient stringrequired
The payer, as a recipient.
amount decimal stringrequired
USDC to send back, dollars and cents.
reference string
Bank refunds only, as on a payout.

Notes

  • Where the payment and the refund are both dollars, refunds never exceed what the payment received (409 refund_exceeds_payment). With an Idempotency-Key a replay returns the same refund.
  • Events refund.created, refund.<state>. Once the refund is paid, a refund journal entry: Dr refunds, Dr fees_set, Cr wallet.

Errors

  • 400 body_invalid
  • 400 amount_invalid
  • 404 payment_unknown
  • 409 refund_exceeds_payment
  • 403 refunds_merchant_only
  • 503 payouts_unavailable
  • 400 amount_invalid
  • 400 amount_too_small
  • 400 reference_invalid
  • 400 external_id_invalid
  • 400 recipient_other_customer
  • 404 recipient_unknown
  • 404 wallet_unknown
  • 409 recipient_disabled
  • 409 recipient_incomplete
  • 409 payee_not_ready
  • 409 balance_too_low
  • 409 initiation_required
  • 403 operator_cannot_pay_out
  • 403 platform_fee_not_allowed
  • 503 bridge_wallets_disabled
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.