Refund a payment

Refund a completed payment intent and Natural returns the money to the originating card, funded from the merchant’s wallet.

Create the refund

Create it with POST /refunds. Name the intent, and set amountMinor for a partial refund or omit it to refund everything still refundable.

cURL

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
curl -X POST https://api.natural.com/refunds \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "paymentIntentId": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
        "amountMinor": 1000,
        "currency": "USD",
        "reason": "requested_by_customer"
      }
    }
  }'

Watch the refund

Read it with GET /refunds/{refundId}. A finished refund reads succeeded or processedAs.

When a refund is refused

refund_payment_not_refundable: the intent has no succeeded card payment.
refund_amount_exceeds_refundable: the amount is more than what remains.
refund_in_progress: another refund of this payment is still pending. The error names it in pendingRefundId; wait for it to finish.
refund_chargeback_open: the payer disputed the payment, so it cannot be refunded.
refund_funds_unavailable: your wallet balance cannot cover the amount. Deposit funds and retry.

List refunds

GET /refunds lists your refunds newest first. Filter by paymentIntentId to see every refund of one payment.

cURL

curl "https://api.natural.com/refunds?paymentIntentId=pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Overview

Common use cases

Products

Guides

Create the refund

Watch the refund

When a refund is refused

List refunds

​Create the refund

​Watch the refund

​When a refund is refused

​List refunds

Create the refund

Watch the refund

When a refund is refused

List refunds