Refunds

A refund returns money from a settled payment back to the payer. Refunds can be full or partial, and they are initiated via the API — there is no automatic refund trigger.

⚠️

Refunds can only be requested within 180 days of the original payment being taken.

How refunds work

When you create a refund, Pinch debits the refund amount from your merchant settlement account and returns it to the payer's payment method. The lifecycle is:

1. You call POST /refunds → status becomes requested
2. Pinch picks it up in the next processing run → status moves to pending-return
3. Funds are debited from your account → pending-clearance
4. Processing completes → completed

Monitor the refund-created and refund-updated webhook events (or poll List Refunds) to track progress. See Refund Statuses for the full status reference.

Full vs partial refund

• Full refund — set amount to the original payment amount (in cents). Pinch refunds the entire payment.
• Partial refund — set amount to a smaller value in cents. For example, to refund $25.00 of a $100.00 payment, set amount: 2500.

{
  "paymentId": "pmt_abc123",
  "amount": 10000,
  "reason": "Duplicate charge"
}

{
  "paymentId": "pmt_abc123",
  "amount": 2500,
  "reason": "Partial cancellation"
}

What happens to fees

By default, Pinch does not return processing fees when you issue a refund — the merchant absorbs the original processing cost.

The response includes two fee-related fields:

If your fee schedule includes refundable fees, refundedFees will be non-zero. Contact [email protected] for details on your specific fee schedule.

Replay protection with idempotency

To prevent duplicate refunds (e.g. from retrying a failed network request), use the nonce field.

{
  "paymentId": "pmt_abc123",
  "amount": 10000,
  "reason": "Customer request",
  "nonce": "refund-pmt_abc123-unique-key"
}

If you send the same nonce twice, Pinch returns the existing refund rather than creating a duplicate.

Tracking refunds with webhooks

Subscribe to the following event types on your webhook to be notified of refund state changes:

See the Events Guide for the full event payloads.

Querying refunds

• List refunds — GET /refunds — paged, filterable by date range.
• Get a refund — GET /refund/{id} — fetch a single refund by its ref_ prefixed ID.
• Check replay protection key — POST /refunds/nonce — confirm whether a given nonce has already been processed.

Common questions

Can I refund a payment that hasn't settled yet?
No. The payment must be in a settled or approved state. You cannot refund a scheduled or processing payment — cancel it instead using Delete Payment.

What if the refund fails?
The refund will move to failed or cancelled-declined status. Contact [email protected] with the refund ID for assistance.

Can I partially refund multiple times?
Yes. You can issue multiple partial refunds against a single payment as long as the sum does not exceed the original payment amount and each refund is within the 180-day window.

Does the payer receive an email?
Pinch sends the payer a notification email when the refund is processed. The original payment method is credited.