Home
API Reference
Start typing to search…

Refund

Allows to control the refunds through API call

Refunds are available for transactions that have been successfully charged and not yet refunded. The refunded amount will be returned to the same card used for the original transaction and may include or exclude the merchant's processing fee, depending on agreements and account configurations.

Refund Types

  • Full Refund: A full refund returns the entire transaction amount to the customer and can only be processed once per transaction.
  • Partial Refund: A partial refund returns a portion of the transaction amount. Multiple partial refunds can be issued, but the total refunded amount cannot exceed the original transaction total.

Refund Response Statuses

When processing a refund, you may encounter several response statuses, depending on the configuration. The available response statuses are:

  • PENDING: The refund request is being processed. The system verifies the Tap Merchant Wallet available balance (the available balance consists of matured funds ready for settlement) and checks for any cancellation attempts. If approved, the refund is forwarded to the bank, and the status will change to REFUNDED. The bank will credit the customer's account within a specified timeframe.
  • REFUNDED: The refund has been successfully processed.
  • DECLINED: The refund was unsuccessful, generally due to various factors such as bank refusal or policy restrictions.
  • FAILED: The refund was unsuccessful due to an internal system issue within Tap Payments.
  • RESTRICTED: The refund was unsuccessful because of a limit or restriction imposed, often due to a card issuer's decline.
  • Other status include UNKNOWN", "TIMED_OUT", "ACCEPTED" (Refer Refund Logic v2)

In case of unsuccessful refunds, please reach out to the Tap Support Team for assistance.

Refund Logic V2

In this updated refund process, the following statuses will be returned to indicate the state of a refund request:

  • REFUNDED: The refund has been successfully processed.
  • ACCEPTED: The refund request has been accepted and is pending processing by Tap Payments team.
  • REJECTED: The refund request has been rejected by Tap.
📘

Please note: To enable v2 logic, you’ll need to contact the Tap Support Team, as it is currently in beta.

Process Flow

  1. Handling of Accepted Refunds:
    • If the request is ACCEPTED, the Tap Payments team will begin the refund process. During this period, the status will remain ACCEPTED until the refund is completed.
    • The Tap Payments team will manage all interactions with the issuer, payment schemes, and other relevant parties to ensure the refund is processed successfully. Any potential delays or issues will be handled internally by Tap Payments, but the status will remain as ACCEPTED during this process.
  2. Completion of Refund:
    • Once the refund is finalized, the status will be updated to REFUNDED, indicating that the funds have been returned to the customer.
    • The completion of the refund will trigger a webhook notification to your server (post.url), ensuring real-time updates on the refund status.

Sample Request

{
	"charge_id": "chg_TS07A2120231341g9R42703981",
	"amount": 1,
	"currency": "KWD",
	"description": "Test Description",
	"reason": "requested_by_customer",
	"reference": {
		"merchant": "txn_0001"
	},
	"metadata": {
		"udf1": "test1",
		"udf2": "test2"
	},
	"post": {
		"url": "http://your_url.com/post"
	}
}

Sample Response

{
  "id": "re_xxxx",
  "object": "refund",
  "api_version": "V2",
  "live_mode": false,
  "amount": 3,
  "charge_id": "chg_xxxx",
  "created": "1723481040882",
  "date": "1723481042085",
  "currency": "AED",
  "status": "REFUNDED",
  "reference": {
    "id": "xxxx",
    "gateway": "xxxx",
    "payment": "xxxx",
    "acquirer": "xxxx"
  },
  "response": {
    "code": "000",
    "message": "Refunded"
  },
  "post": {
    "status": "PENDING",
    "url": "http://your_website.com/post_url"
  },
  "acquirer": {
    "response": {
      "code": "000",
      "message": "Refunded"
    }
  },
  "gateway": {
    "response": {
      "code": "00",
      "message": "Approved"
    }
  },
  "method": "CREATE",
  "transaction": {
    "timezone": "UTC+03:00",
    "asynchronous": false,
    "amount": 3,
    "currency": "AED",
    "date": {
      "created": 1723481040882,
      "completed": 1723481042085
    }
  },
  "wallet": {
    "debit": false
  },
  "merchant": {
    "id": "xxxx"
  },
  "reverse_destination": false,
  "reason": "The product is out of stock"
}

Sample Response for V2 Logic

{
    "id": "re_xxxx",
    "object": "refund",
    "api_version": "V2",
    "live_mode": true,
    "amount": 3,
    "charge_id": "chg_xxxx",
    "created": "1731320643023",
    "date": "1731320643947",
    "currency": "AED",
    "status": "ACCEPTED",
    "reference": {
        "id": "xxxx",
        "gateway": "mada_xxxx",
        "payment": "activity_xxxx",
        "acquirer": "xxxxxx",
        "merchant": "xxxxxxxxxxxxxxxxxx",
        "idempotent": "xxxxxxxxxxxxxxxxxx"
    },
    "response": {
        "code": "101",
        "message": "Accepted"
    },
    "post": {
        "status": "PENDING",
        "url": "https://example.com/notifications/tap"
    },
    "gateway": {
        "response": {
            "code": "199",
            "message": "Transaction exceeds the allowed time limit"
        }
    },
    "method": "REFUND",
    "product": "",
    "charge": {
        "id": "chg_xxxxxxxxxxxxxxxxxxxxxx",
        "object": "charge",
        "live_mode": true,
        "customer_initiated": true,
        "api_version": "V2",
        "method": "GET",
        "status": "CAPTURED",
        "amount": 3,
        "currency": "AED",
        "threeDSecure": false,
        "card_threeDSecure": false,
        "save_card": false,
        "product": "",
        "description": "generic description",
        "transaction": {
            "authorization_id": "xxxxx",
            "timezone": "UTC+03:00",
            "created": "1727394279301",
            "expiry": {
                "period": 30,
                "type": "MINUTE"
            },
            "asynchronous": false,
            "amount": 3,
            "currency": "AED",
            "date": {
                "created": 1727394279301,
                "completed": 1727394280470,
                "posted": 1727308800000
            }
        },
        "reference": {
            "track": "tck_xxxxxxxxxxxxxxxxxxxxxx",
            "payment": "xxxxxxxxxxxxxxxx",
            "trace_id": "xxxxxxxxxxxxxxxx",
            "order": "generic order id",
            "idempotent": "xxxxxxxxxxxxxxxx",
            "acquirer": "xxxxxxx",
            "gateway": "mada_xxxxxxxxxxxxxxx"
        },
        "response": {
            "code": "000",
            "message": "Captured"
        },
        "gateway": {
            "response": {
                "code": "000",
                "message": "Approved"
            }
        },
        "card": {
            "object": "card",
            "first_six": "xxxxxx",
            "first_eight": "xxxxxxxx",
            "scheme": "MADA",
            "brand": "VISA",
            "last_four": "xxxx",
            "name": "John Doe",
            "expiry": {
                "month": "MM",
                "year": "YY"
            }
        },
        "receipt": {
            "id": "xxxxxxxxxxxxxxxxxx",
            "email": true,
            "sms": true
        },
        "customer": {
            "id": "cus_xxxxxxxxxxxxxxxxxxxxxx",
            "first_name": "John",
            "last_name": "Doe",
            "email": "[email protected]",
            "phone": {
                "country_code": "+xxx",
                "number": "xxxxxxxx"
            }
        },
        "merchant": {
            "country": "AE",
            "currency": "AED",
            "id": "xxxxxxxx"
        },
        "source": {
            "object": "source",
            "type": "CARD_NOT_PRESENT",
            "payment_type": "DEBIT",
            "channel": "INTERNET",
            "id": "tok_xxxxxxxxxxxxxxxxxxxxxx",
            "on_file": false,
            "payment_method": "APPLE_PAY"
        },
        "redirect": {
            "status": "SUCCESS",
            "url": "https://example.com/complete"
        },
        "post": {
            "attempt": 1,
            "status": "SUCCESS",
            "url": "https://example.com/notifications/tap"
        },
        "activities": [
            {
                "id": "activity_xxxxxxxxxxxxxxxxxxxxxx",
                "object": "activity",
                "created": 1727394279301,
                "status": "INITIATED",
                "currency": "AED",
                "amount": 3,
                "remarks": "charge - created",
                "txn_id": "chg_xxxxxxxxxxxxxxxxxxxxxx"
            },
            {
                "id": "activity_xxxxxxxxxxxxxxxxxxxxxx",
                "object": "activity",
                "created": 1727394280440,
                "status": "CAPTURED",
                "currency": "AED",
                "amount": 3,
                "remarks": "charge - captured",
                "txn_id": "chg_xxxxxxxxxxxxxxxxxxxxxx"
            }
        ],
        "auto_reversed": false
    },
    "transaction": {
        "authorization_id": "",
        "timezone": "UTC+03:00",
        "asynchronous": false,
        "amount": 3,
        "currency": "AED",
        "date": {
            "created": 1731320643023,
            "completed": 1731320643947
        }
    },
    "wallet": {
        "debit": false,
        "auto_debit": true
    },
    "merchant": {
        "country": "AE",
        "currency": "AED",
        "id": "xxxxxxxx"
    },
    "reverse_destination": false,
    "reason": "generic reason"
}