Refund a card payment

Return part or all of a successful card payment to the card that paid.

Refunding for a customer? Pass their party ID as customerPartyId on each call. Your agent needs permission to act on their behalf.

Create the refund

Create a refund with either paymentIntentId or cardPaymentId, not both. Set amount for a partial refund. Omit it to refund the remaining amount.

import uuid
from naturalpay import Natural

# Set NATURAL_API_KEY to your agent's API key.
client = Natural(instance_id=str(uuid.uuid4()))

refund = client.refunds.create(
    payment_intent_id="pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
    amount=1000,
    reason="requestedByPayer",
    idempotency_key=str(uuid.uuid4()),
)

import Natural from "@naturalpay/sdk";

// Set NATURAL_API_KEY to your agent's API key.
const client = new Natural();
const refund = await client.refunds.create(
  {
    paymentIntentId: "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
    amount: 1000,
    reason: "requestedByPayer",
    idempotencyKey: crypto.randomUUID(),
  },
  { instanceId: crypto.randomUUID() },
);

natural refunds create \
  --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
  --amount 1000 \
  --reason requestedByPayer \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Refund $10 of payment intent pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 at the payer's request.

# 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",
        "amount": 1000,
        "reason": "requestedByPayer"
      }
    }
  }'

The response includes the refund ID and its status.

Watch the refund

Get the refund to check its status, or subscribe to refund.succeeded and refund.failed webhooks.

result = client.refunds.get(refund.data.id)

const result = await client.refunds.get({ refundId: refund.data.id });

natural refunds get --refund-id rfd_019d0a1b2c3d4e5f60718293a4b5c6e0

Has that refund completed?

curl https://api.natural.com/refunds/rfd_019d0a1b2c3d4e5f60718293a4b5c6e0 \
  -H "Authorization: Bearer $NATURAL_API_KEY"

A finished refund has status succeeded or failed. If it fails, check failure for the reason.

List refunds

List refunds to review recent activity. Filter by paymentIntentId or cardPaymentId to see refunds for one payment.

refunds = client.refunds.list(
    payment_intent_id="pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
)

const refunds = await client.refunds.list({
  paymentIntentId: "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
});

natural refunds list \
  --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7

List refunds for payment intent pmi_019d0a1b2c3d4e5f60718293a4b5c6d7.

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

Handle a refused refund

Another refund is pending: wait for it to finish before requesting another.
The amount is too high: request no more than the remaining refundable amount.
Insufficient funds: add funds to your wallet, then retry.
A chargeback blocks the refund: review the dispute before proceeding.

See Refund errors for the full list of codes and causes.

Overview

Common use cases

Products

Guides

Create the refund

Watch the refund

List refunds

Handle a refused refund

​Create the refund

​Watch the refund

​List refunds

​Handle a refused refund

Create the refund

Watch the refund

List refunds

Handle a refused refund