Refunds API

Refunds API https://paystack.com/docs/api/refund/

class djpaystack.api.refunds.RefundAPI(client)[source]

Bases: BaseAPI

Paystack Refunds API

The Refunds API allows you to create and manage refunds for previously successful transactions.

create(transaction: str, amount: int | None = None, currency: str | None = None, customer_note: str | None = None, merchant_note: str | None = None) → Dict[str, Any][source]

Create a refund (full or partial).

Parameters:

  • transaction – Transaction reference or ID

  • amount – Amount to refund in subunit. If not provided, full refund.

  • currency – Currency code

  • customer_note – Note for customer

  • merchant_note – Note for merchant records

Returns:

Refund details

list(per_page: int = 50, page: int | None = None, reference: str | None = None, currency: str | None = None, from_date: str | None = None, to_date: str | None = None) → Dict[str, Any][source]

List refunds

fetch(reference: str) → Dict[str, Any][source]

Fetch refund

retry(refund_id: str, account_number: str, bank_id: str, currency: str = 'NGN') → Dict[str, Any][source]

Retry a refund that requires customer bank details.

Use this when a refund status is ‘needs-attention’ (i.e. when you receive a refund.needs-attention webhook event). The customer’s bank account details are needed to complete the refund.

Parameters:

  • refund_id – The refund ID

  • account_number – Customer’s bank account number

  • bank_id – Customer’s bank ID

  • currency – Currency code (default: ‘NGN’)

Returns:

Retried refund details

Quick Reference

from djpaystack import PaystackClient
client = PaystackClient()

# Create refund
client.refunds.create(transaction='123456', amount=50000)

# List refunds
client.refunds.list(page=1, per_page=50)

# Fetch refund
client.refunds.fetch(reference='refund-ref')

# Retry a stuck refund (status = refund.needs-attention)
client.refunds.retry(id='123456')

Webhook Events

  • refund.pending — Refund initiated

  • refund.processing — Refund in progress

  • refund.processed — Refund completed

  • refund.failed — Refund failed

  • refund.needs-attention — Requires manual retry via retry()