Refunds

How it works

A refund returns already captured money through the original connector. Releasing an uncaptured authorization uses payment cancellation instead.

Implementation

Create a refund with payment_id and, for a partial refund, amount in minor units. Store your own refund_id to reconcile uncertain retries; do not assume every endpoint supports an idempotency header. Product line credits associate the refund with catalog lines for accounting. Inspect pending, review, succeeded or failed status and wait for the event or retrieved result. A submitted request alone does not prove that the buyer has received funds.

Create a refund

Track the refund

Related guides

• Accept payments
• Products and line items
• Webhook events
• Invoices & credit notes

Request examples

curl -X POST https://api.spicepay.net/refunds \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_id": "pay_xxxxx",
    "refund_id": "ref_order_2042_1",
    "amount": 1000,
    "reason": "requested_by_customer"
  }'

curl https://api.spicepay.net/payments/pay_xxxxx/lines \
  -H 'api-key: YOUR_API_KEY'

curl -X POST https://api.spicepay.net/refunds \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_id": "pay_xxxxx",
    "amount": 2500,
    "line_credits": [
      { "line_id": "ppl_xxxxx", "quantity": 1, "amount": 2000, "tax_amount": 319 }
    ]
  }'

Credit product lines

Retrieve the payment lines, then associate each credit with its line_id. Supply the quantity, credited amount and tax amount that match the intended correction. Keep line totals consistent with the refund amount and the remaining refundable balance. Use the line-credit request shown above when issuing a partial product refund.