Refund Preview

The Refund Preview endpoint calculates the expected refund breakdown for a completed checkout session — including any fees, taxes, or partial amounts — without processing an actual refund. Use it to display an accurate refund summary to the merchant or customer before submitting a refund request.

This endpoint returns a preview only. No funds are moved. To process the refund, use the Transactions API.

How It Works

1

Identify the completed checkout

Retrieve the checkoutId of the session you want to refund using GET /v2/checkout/{checkoutId}. Confirm its status is COMPLETED.

2

Request the refund preview

Call POST /v2/checkout/refund/preview with the checkoutId and the amount you intend to refund. The response returns the calculated breakdown.

3

Review the breakdown

Inspect the preview response before presenting it to the merchant or triggering an actual refund via the Transactions API.

API Reference

Refund Preview

Refund Preview

post

/v2/checkout/refund/preview

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Body

amountnumberRequired

Original refund amount.

network_feenumberRequired

Network fee.

final_amountnumberRequired

Final amount to be refunded.

currency_codestring · enumRequired

Currency code

Possible values:

refund_transaction_idstringRequired

Refund transaction id

sale_transaction_idstringOptional

Sale transaction id

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

merchant_referencestring · max: 50Optional

Reference provided by Merchant to identify the Checkout and the transaction initiated from it

Pattern: ^[^=+\-@].*

expiry_timestring · dateOptional

Expiry time of the Refund preview page defaults to 14 days from creation time. If a user tries to visit or use an expired Refund preview, an error will be shown.

reasonstringOptional

Reason for refund

entity_namestringRequired

Entity name

merchant_urlstringRequired

URL belonging to the Merchant website, where the Customer would be redirected after the Refund Preview has been completed.

email_notification_requiredbooleanOptional

Whether email notification required or not.

Default: true

Responses

200

Successful

application/json

idstringRequired

Refund preview ID

urlstringOptional

URL of the Refund preview

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

post/v2/checkout/refund/preview

POST /oidc/checkout-service/v2/checkout/refund/preview HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 424

{
  "amount": 1,
  "network_fee": 1,
  "final_amount": 1,
  "currency_code": "AED",
  "refund_transaction_id": "text",
  "sale_transaction_id": "text",
  "entity_id": "text",
  "merchant_reference": "text",
  "expiry_time": "2026-01-01",
  "reason": "text",
  "entity_name": "text",
  "merchant_url": "text",
  "email_notification_required": true,
  "notification_methods": {
    "email": {
      "email_address": "text"
    }
  },
  "details": {
    "crypto": {
      "crypto_amount": 1,
      "crypto_currency_code": "text"
    }
  }
}

{
  "id": "text",
  "url": "text",
  "details": {
    "errors": [
      {}
    ]
  }
}

---

See Checkout Sessions for how to retrieve a checkout ID.