Overview

This document describes the refund endpoints for Payment Pages. These endpoints allow merchants to initiate and retrieve refund information for card payments made through payment pages.

Currently, only full refunds for card payments are supported. Once initiated, the refund will be processed in the background and you'll know its progress by webhook type REFUND_STATUS_UPDATE(see handle-webhooks)

A refunded payment will appear as 2 entries on the statement one for the payment and another one for the refund, and please note that we will charge a processing fee on refunded payments too. For example: if a payment with gross amount $5 and net amount $4.5 is refunded, you'll see a $4.5 payment entry and a -$5.0 refund entry.

1. Initiate Refund

Initiates a refund for a payment page. Only payment page in PAID status can be refunded

curl --location --request POST 'https://api.breeze.cash/v1/payment_pages/:paymentPageId/refund' \
-u "YOUR_API_KEY:" 

A successful response will look like:

{
    "status": "SUCCEEDED",
    "data": {
        "id": "ref_pay_abc123xyz",
        "status": "new"
    }
}

• data.id: A unique identifier for tracking this refund request on Breeze’s side.
• data.status: The status of the refund request

2. Retrieve a Refund

Retrieves detailed information about a specific refund.

curl --location 'https://api.breeze.cash/v1/payment_pages/:paymentPageId/refund/:refundId' \
-u "YOUR_API_KEY:"

A successful response will look like:

{
    "status": "SUCCEEDED",
    "data": {
        "id": "ref_pay_abc123xyz",
        "status": "succeeded",
        "merchantId": "mch_abc123xyz",
        ...
    }
}

• data.id: A unique identifier for tracking this refund request on Breeze’s side.
• data.status: The status of the refund request

3. Handle Webhooks

When there is any update to the refund request status, Breeze will send a webhook notification to your server or application. Here's a minimal example of what that webhook payload might look like

{
  "type": "REFUND_STATUS_UPDATE",
  "data": {
    "pageId": "page_abc123xyz",
    "refundId": "ref_pay_abc123xyz",
    "status": "succeeded",
    ...
  },
  "signature": "webhook_payload_signature"
}

Refund Status