Refunds

Refunds are reversals on an existing transfer. The Python SDK does not expose a top-level client.refunds namespace — refunds live on the Transfers resource as client.transfers.create_refund(...).

No standalone client.refunds.* namespace ships in 0.1.x.

Methods

`create_refund` (on `transfers`)

reversal = client.transfers.create_refund(
    "tr_123",
    refund_amount=500,                     # cents; partial allowed
    tags={"reason": "broken_widget"},
    idempotency_key="refund-tr_123-1",
)

Returns the reversal as a Transfer object (the API models reversals as transfers in the opposite direction). Pass refund_amount equal to the original transfer's amount for a full refund.

Object shape

The reversal is a Transfer — see Transfers for the field list.

The most relevant fields on a reversal:

Field	Notes
`id`	The reversal's own ID.
`type`	Distinguishes reversal vs. original transfer.
`state`	`"PENDING"`, `"SUCCEEDED"`, `"FAILED"`.
`amount`	The refunded amount (positive integer, cents).
`failure_code` / `failure_message`	Populated if the reversal fails.

Examples

Full refund on a transfer

original = client.transfers.retrieve("tr_123")
reversal = client.transfers.create_refund(
    original.id,
    refund_amount=original.amount,
    idempotency_key=f"refund-{original.id}-full",
)
assert reversal.state in {"PENDING", "SUCCEEDED"}

Partial refund with a reason tag

client.transfers.create_refund(
    "tr_123",
    refund_amount=500,
    tags={"reason": "shipping_damage", "ticket": "SUP-4421"},
    idempotency_key="refund-tr_123-shipping",
)

Idempotent refund from a webhook handler

def on_dispute_won(event):
    dispute = event.data
    client.transfers.create_refund(
        dispute["transfer_id"],
        refund_amount=dispute["amount"],
        idempotency_key=f"refund-dispute-{dispute['id']}",
    )