Skip to main content
POST
Create Refund

Overview

Issue a full or partial refund for a completed collection. The refund amount is debited from your business wallet and credited to the payer’s Fyatu account. Important: Each collection can only be refunded once. Choose between a full refund or a partial refund at the time of processing.

Path Parameters

Request Body

Refund Modes

Use FULL mode to avoid calculation errors. The system automatically determines the maximum refundable amount (net amount after fees).

Refund Reason Codes

Use one of these predefined reason codes in the reason field: You can also retrieve these programmatically via GET /api/v3/refunds/reasons.

Response

Refund Rules

  1. Only Completed Collections: Cannot refund pending, expired, or failed payments
  2. One Refund Per Collection: Each collection can only be refunded once
  3. Maximum Refundable: Net amount (original amount minus fees)
  4. Fees Non-Refundable: Processing fees are retained
  5. Wallet Balance Required: Your business wallet must have sufficient balance

Example Usage

Example Response (Full Refund)

Example Response (Partial Refund)

Amount Exceeds Maximum

If you request a partial refund amount that exceeds the maximum refundable, the API will return an error with the maximum amount:

Refund Amount Calculation

Processing fees are non-refundable. The maximum refund amount is the net amount you received, not the original payment amount.

Error Responses

Collection Status After Refund

  • Full Refund: Collection status changes to REFUNDED
  • Partial Refund: Collection status changes to PARTIALLY_REFUNDED
  • Customer Notification: Payer receives notification of the refund
Keep track of refund IDs to handle customer inquiries and for accounting purposes.

Authorizations

Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

collectionId
string
required

Collection ID or batch ID

Body

application/json
mode
enum<string>
default:FULL

Refund mode: FULL (auto-calculate) or PARTIAL (specify amount)

Available options:
FULL,
PARTIAL
amount
number

Refund amount (required for PARTIAL mode)

reason
enum<string>
default:CUSTOMER_REQUEST

Reason code for refund

Available options:
DUPLICATE_PAYMENT,
FRAUDULENT,
CUSTOMER_REQUEST,
ORDER_CANCELLED,
PRODUCT_NOT_DELIVERED,
PRODUCT_NOT_AS_DESCRIBED,
PRICING_ERROR,
OTHER

Response

Refund created successfully

success
boolean
Example:

true

status
integer
Example:

201

message
string
data
object
meta
object