Notch Pay allows you to process refunds for payments that have been completed. This guide explains how to issue full or partial refunds, track refund status, and handle refund-related events.

​
Overview

With Notch Pay’s refund functionality, you can:
  • Issue full or partial refunds for completed payments
  • Track the status of refunds
  • Receive notifications when refunds are processed
  • View refund history for reconciliation

Key Benefits

  • Simple API for processing refunds
  • Support for partial refunds
  • Automatic handling of refund logistics
  • Detailed refund tracking
  • Webhook notifications for refund events

Use Cases

  • Customer returns or cancellations
  • Service delivery issues
  • Billing adjustments
  • Dispute resolutions
  • Promotional refunds or credits

​
Processing Refunds

​
From the Dashboard

The easiest way to process a refund is through your Notch Pay dashboard:
  1. Log in to your Notch Pay Business suite
  2. Go to Payments > Refunds
  3. Find the payment you want to refund
  4. Click the Refund button
  5. Enter the refund amount (for partial refunds) or select Full Refund
  6. Add a reason for the refund (optional)
  7. Click Process Refund

​
Using the API

You can also process refunds programmatically using the API: 
// Process a refund
fetch('https://api.notchpay.co/refunds', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment: 'pay_123456789', // Payment ID or reference
    amount: 5000, // For partial refunds (in the smallest currency unit)
    // Omit amount for full refunds
    reason: 'Customer requested cancellation',
    metadata: { // Optional
      order_id: '12345',
      customer_service_rep: 'jane_doe'
    }
  })
})
.then(response => response.json())
.then(data => {
  console.log(data.refund.id); // The refund ID
  console.log(data.refund.status); // The refund status
})

​
Refund Types

​
Full Refunds

A full refund returns the entire payment amount to the customer: 
fetch('https://api.notchpay.co/refunds', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment: 'pay_123456789',
    reason: 'Product returned'
  })
})

​
Partial Refunds

A partial refund returns only a portion of the payment: 
fetch('https://api.notchpay.co/refunds', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment: 'pay_123456789',
    amount: 2500, // Refund half of a 5000 payment
    reason: 'Partial order cancellation'
  })
})

​
Refund Statuses

Refunds can have the following statuses:
StatusDescription
pendingThe refund has been initiated but not yet processed
processingThe refund is being processed by the payment provider
completeThe refund has been successfully processed
failedThe refund could not be processed

​
Retrieving Refunds

​
Retrieving a Single Refund

To retrieve information about a specific refund: 
fetch('https://api.notchpay.co/refunds/ref_123456789', {
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data.refund);
})

​
Listing Refunds for a Payment

To retrieve all refunds for a specific payment: 
fetch('https://api.notchpay.co/payments/pay_123456789/refunds', {
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data.refunds);
})

​
Listing All Refunds

To retrieve all refunds for your account: 
fetch('https://api.notchpay.co/refunds', {
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data.refunds);
})

​
Refund Webhooks

To receive notifications about refund events, set up webhooks for the following events:
  • refund.created: A refund has been created
  • refund.complete: A refund has been successfully processed
  • refund.failed: A refund has failed
Example webhook payload for a refund event: 
{
  "type": "refund.complete",
  "data": {
    "id": "ref_123456789",
    "amount": 5000,
    "currency": "XAF",
    "payment": "pay_123456789",
    "reason": "Customer requested cancellation",
    "status": "complete",
    "created_at": "2023-01-01T12:00:00Z",
    "metadata": {
      "order_id": "12345",
      "customer_service_rep": "jane_doe"
    }
  }
}

​
Refund Limitations

When processing refunds, be aware of the following limitations:
  1. Time Limits: Refunds can typically be processed within 90 days of the original payment
  2. Payment Method Restrictions: Some payment methods may have restrictions on refunds
  3. Processing Time: Refunds may take several days to process, depending on the payment method
  4. Fees: While Notch Pay doesn’t charge additional fees for refunds, the original processing fees are typically not refunded

​
Best Practices

  1. Clear Refund Policy: Establish a clear refund policy for your customers
  2. Prompt Processing: Process refunds promptly to maintain customer satisfaction
  3. Detailed Records: Keep detailed records of refund reasons for reconciliation
  4. Communication: Keep customers informed about the status of their refunds
  5. Partial Refunds: Consider offering partial refunds when appropriate
  6. Metadata: Use metadata to link refunds to your internal systems

​
Troubleshooting

​
Common Issues

  • Insufficient Funds: Ensure your Notch Pay account has sufficient funds to process the refund
  • Invalid Payment: Verify that the payment ID or reference is correct
  • Payment Not Eligible: Check that the payment is in a state that allows refunds
  • Amount Exceeds Payment: Ensure the refund amount doesn’t exceed the original payment amount

​
Support

If you encounter issues with refunds: