Refunds

Refunds allow you to return funds to customers for successful payments. NjiaPay supports both full and partial refunds through a simple API.

When to Refund

Common scenarios for refunds:

• Customer requests cancellation
• Product/service not delivered
• Duplicate payment
• Fraud detection
• Quality issues
• Order cancellation

Refund Types

Full Refund

Return the entire payment amount to the customer.

Partial Refund

Return only a portion of the payment amount.

Multiple partial refunds are possible (depending on PSP support) as long as the total doesn't exceed the original payment amount.

Creating a Refund

To refund a payment, use the refund endpoint:

curl -X POST https://api.njiapay.com/api/intents/{intent_id}/refund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "reason": "customer_request"
  }'

Parameters:

• amount (required): Amount to refund in minor units (must be ≤ original amount minus previous refunds)
• reason (optional): Reason for refund (fraud, customer_request, return, duplicate, other)

Response:

{
  "id": 789,
  "intent_id": "550e8400-e29b-41d4-a716-446655440000",
  "attempt_id": 456,
  "amount": 5000,
  "status": "initiated",
  "created": "2024-01-15T10:30:00Z",
  "reason": "customer_request"
}

Refund Statuses

Refund Webhooks

You'll receive a Refund webhook event when refund status changes:

{
  "type": "refund",
  "created": "2024-09-01T00:00:00Z",
  "content": {
    "refund_id": 789,
    "type": "full",
    "intent_id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_id": "order_12345",
    "purchaser_id": "customer_abc",
    "amount": 20000,
    "currency": "ZAR",
    "status": "success"
  }
}

refund_id is the id returned when you created the refund. Use it to match the event to your refund record, since an intent can have several refunds and you receive an event on every status transition.

Important Limitations

PSP-Specific Limitations

Different payment providers have different refund rules:

Timing Windows:

• Some PSPs only allow same-day refunds
• Others allow refunds up to 90 days after payment
• Check with your PSP for specific limits

Payment Methods:

• Not all payment methods support refunds
• Some methods support partial refunds, others only full
• Check payment method compatibility

Validation Rules

• Only successful payments can be refunded
• API key must belong to same merchant as payment
• Refund amount must not exceed: original_amount - previous_refunds
• Some PSPs may have minimum refund amounts

Best Practices

✅ DO

• Process refunds promptly
• Send refund confirmation to customers
• Log all refund attempts
• Handle refund webhooks
• Check refund status periodically
• Document refund reasons

❌ DON'T

• Refund before verifying order details
• Ignore refund failure notifications
• Assume refunds are instant
• Refund more than original amount
• Skip customer notifications

Related Topics