Payments - Check Balance and Apply PM Data

POST /v2/payments/{id}/eligibility/check-balance-and-apply-pm-data

Try it (cURL):

cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payments/{id}/eligibility/check-balance-and-apply-pm-data \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "payment_methods": [
    {
      "gift_card": {
        "givex": {
          "number": "<string>",
          "cvc": "<string>"
        }
      }
    }
  ]
}
'

Response (200):

application/json

{
  "balances": [
    {
      "payment_method_data": {
        "gift_card": {
          "givex": {
            "number": "<string>",
            "cvc": "<string>"
          }
        }
      },
      "eligibility": {
        "success": {
          "balance": 123,
          "applicable_amount": 123,
          "currency": "AED"
        }
      }
    }
  ],
  "remaining_amount": 123,
  "currency": "AED",
  "requires_additional_pm_data": true,
  "surcharge_details": [
    {
      "payment_method_type": "card",
      "payment_method_subtype": "ach",
      "surcharge_details": {
        "surcharge": {
          "type": "fixed",
          "value": 123
        },
        "display_surcharge_amount": 123,
        "display_tax_on_surcharge_amount": 123,
        "display_total_surcharge_amount": 123,
        "tax_on_surcharge": {
          "percentage": 123
        }
      }
    }
  ]
}

---

Authorizations

• api-key (string, header) — required Publishable keys are a type of keys that can be public and have limited scope of usage.

---

Headers

• X-Profile-Id (string) — required Profile ID associated to the payment intent

---

Path Parameters

• id (string) — required The global payment id

---

Body

Content-Type: application/json

• payment_methods (object[]) — required

---

Response (200 — application/json)

• balances (object[]) — required Apply the Payment Method Data

• remaining_amount (integer) — required This Unit struct represents MinorUnit in which core amount works

• currency (enum) — required The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available currency options (expand)

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL

• requires_additional_pm_data (boolean) — required Whether the applied payment method balance is enough for the order amount or additional PM is required

• surcharge_details (object[] | null) — Show child attributes in response

---

Notes / Actions

• Apply the provided payment method data to check balances and eligibility for the payment intent.

• The response includes remaining_amount, applied balances, whether additional payment method data is required, and any surcharge details.

---

Was this page helpful?

Yes / No

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/payments/payments--check-balance-and-apply-pm-data.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v2/payments/payments--check-balance-and-apply-pm-data