Skip to main content

​
Overview

You can issue refunds for completed payments. Refunds are sent back to the customer’s Stellar wallet address that was used for the original payment.

​
Creating a Refund

To refund a payment, call POST /payments/{id}/refunds with the amount and asset: 
POST /payments/pt_ABC123/refunds
X-Digest-Key: pk_YOUR_KEY
X-Digest-Timestamp: 1714067192
X-Digest-Signature: YOUR_SIGNATURE

{
  "amount": {
    "value": 1000,
    "asset_id": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
  },
  "description": "Refund for order #1234"
}

​
Refund Rules

  • The payment must be in paid or underpaid_accepted status
  • Refund amount cannot exceed the amount_paid on the payment
  • Only one refund can be in progress per payment at a time
  • The refund is sent to sender_account (the original payer)

​
Refund Statuses

StatusDescription
openRefund created, pending submission
processingRefund transaction submitted to Stellar
refundedRefund completed successfully

​
Non-Custodial Flow

For non-custodial merchant accounts, the refund flow is two steps:
  1. Create refund — POST /payments/{id}/refunds returns an unsigned XDR transaction
  2. Sign and submit — sign the XDR with your Stellar key, then call POST /refunds/{refund_id}/send
For custodial (enterprise) accounts, the refund is processed automatically after creation.