Refunding Payments

API/Endpoint Usage Flow for Refund Process:

1. Customer requests a refund:
   The customer contacts your support team or uses a self-service option in your platform to request a refund.
2. Create a refund request:
   Upon receiving a refund request, your platform should initiate a POST request to the /invoices/:invoiceId/refunds endpoint, including required parameters such as the buyer's email, refund amount, and currency. Replace :invoiceId with the invoice's unique identifier.

🚧

Note - your BitPay ledger must hold funds in excess of the refund amount before you can create the refund request. If you need to verify your ledger balance, you can use an API call, or manually check using your merchant dashboard.

3. Instant Payment Notification (IPN) for refund initiation:
   BitPay sends an IPN to your specified notification URL when the refund is initiated, providing you with the refund details. Your platform should handle the IPN by validating the received data and updating the refund status accordingly.
4. Customer accepts the refund:
   The customer receives an email from BitPay with a link to accept the refund. They need to click the link and provide the required information, such as their wallet address, within a specified time frame.
5. Monitor web-hooks/IPNs (Instant Payment Notifications) for refund status updates:
   BitPay sends additional IPNs to your specified notification URL as the refund status changes, such as when the refund is successfully processed or expires. Your platform should handle these IPNs by updating the refund status and notifying the customer accordingly.
6. Refund completed:
   Once the refund has been processed successfully, your platform should have already updated the refund status based on the received IPN. Notify the customer that their refund has been completed.

Exception Handling and Error Monitoring:

• Customer doesn't accept the refund in time:
  If the customer doesn't accept the refund within the specified time frame, the refund expires. In this case, BitPay sends an IPN indicating the refund's expired status. Update your platform's records and notify the customer to request a new refund and restart the process.
• Handling API errors:
  Properly handle HTTP status codes and error messages returned by the BitPay API. Implement retries for transient errors and notify the customer in case of a permanent error. For example, if a refund request fails due to an incorrect email address, notify the customer to correct their email address and restart the refund process.
• Monitoring for errors:
  Regularly monitor your integration logs and track any errors or exceptions that occur during the refund process. Implement monitoring tools and set up alerts to be notified of any issues that require immediate attention.

Manual Flow for Refund Process:

1. Customer requests a refund:
   The customer contacts your support team or uses a self-service option in your platform to request a refund.
2. Create a refund request:
   Log in to your BitPay merchant dashboard. Navigate to the "Payments" tab. From here, locate the payment that you need to refund. You may need to expand the time range selection. Click on the payment, and then click "Refund" in the top-right corner. You will be prompted to provide the amount to be refunded, and possibly an email address depending on how the customer paid.

🚧

Note - your BitPay ledger must hold funds in excess of the refund amount before you can create the refund request. Check the balance on the "Overview" tab.

3. Monitor refund status:
   You can view the status of the refund from the "Payments" tab if you would like to do so.
4. Customer accepts the refund:
   The customer receives an email from BitPay with a link to accept the refund. They need to click the link and provide the required information, such as their wallet address, within a specified time frame.
5. Refund completed:
   You will see the payment as "Refunded" in your merchant dashboard.