Get Started
Payments Core APIs
Account management APIs
Other APIs
curl --request GET \
--url https://sandbox.hyperswitch.io/subscriptions/{subscription_id} \
--header 'X-Profile-Id: <x-profile-id>' \
--header 'api-key: <api-key>'{
"id": "<string>",
"status": "active",
"profile_id": "<string>",
"merchant_id": "<string>",
"customer_id": "<string>",
"merchant_reference_id": "<string>",
"plan_id": "<string>",
"item_price_id": "<string>",
"client_secret": "<string>",
"coupon_code": "<string>",
"payment": {
"payment_id": "<string>",
"status": "succeeded",
"amount": 123,
"currency": "AED",
"profile_id": "<string>",
"connector": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"return_url": "<string>",
"next_action": {
"redirect_to_url": "<string>",
"type": "redirect_to_url"
},
"payment_experience": "redirect_to_url",
"error_code": "<string>",
"error_message": "<string>",
"payment_method_type": "ach",
"client_secret": "<string>",
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"shipping": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"payment_type": "normal",
"payment_token": "token_sxJdmpUnpNsJk5VWzcjl"
},
"invoice": {
"id": "<string>",
"subscription_id": "<string>",
"merchant_id": "<string>",
"profile_id": "<string>",
"merchant_connector_id": "<string>",
"customer_id": "<string>",
"amount": 123,
"currency": "AED",
"status": "invoice_created",
"payment_intent_id": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"billing_processor_invoice_id": "<string>"
}
}Subscription - Retrieve
Retrieves subscription details by ID.
curl --request GET \
--url https://sandbox.hyperswitch.io/subscriptions/{subscription_id} \
--header 'X-Profile-Id: <x-profile-id>' \
--header 'api-key: <api-key>'{
"id": "<string>",
"status": "active",
"profile_id": "<string>",
"merchant_id": "<string>",
"customer_id": "<string>",
"merchant_reference_id": "<string>",
"plan_id": "<string>",
"item_price_id": "<string>",
"client_secret": "<string>",
"coupon_code": "<string>",
"payment": {
"payment_id": "<string>",
"status": "succeeded",
"amount": 123,
"currency": "AED",
"profile_id": "<string>",
"connector": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"return_url": "<string>",
"next_action": {
"redirect_to_url": "<string>",
"type": "redirect_to_url"
},
"payment_experience": "redirect_to_url",
"error_code": "<string>",
"error_message": "<string>",
"payment_method_type": "ach",
"client_secret": "<string>",
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"shipping": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"payment_type": "normal",
"payment_token": "token_sxJdmpUnpNsJk5VWzcjl"
},
"invoice": {
"id": "<string>",
"subscription_id": "<string>",
"merchant_id": "<string>",
"profile_id": "<string>",
"merchant_connector_id": "<string>",
"customer_id": "<string>",
"amount": 123,
"currency": "AED",
"status": "invoice_created",
"payment_intent_id": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"billing_processor_invoice_id": "<string>"
}
}Authorizations
Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.
Headers
Profile ID for authentication
Path Parameters
The unique identifier for the subscription
Response
Subscription retrieved successfully
Response payload returned after successfully creating a subscription.
Includes details such as subscription ID, status, plan, merchant, and customer info.
A type for subscription_id that can be used for subscription ids
Possible states of a subscription lifecycle.
Created: Subscription was created but not yet activated.Active: Subscription is currently active.InActive: Subscription is inactive.Pending: Subscription is pending activation.Trial: Subscription is in a trial period.Paused: Subscription is paused.Unpaid: Subscription is unpaid.Onetime: Subscription is a one-time payment.Cancelled: Subscription has been cancelled.Failed: Subscription has failed.
active, created, in_active, pending, trial, paused, unpaid, onetime, cancelled, failed A type for profile_id that can be used for business profile ids
A type for merchant_id that can be used for merchant ids
A type for customer_id that can be used for customer ids
Merchant specific Unique identifier.
Identifier for the associated subscription plan.
Identifier for the associated item_price_id for the subscription.
This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK
Optional coupon code applied to this subscription.
Show child attributes
Show child attributes
A type for payment_id that can be used for payment ids
Represents the overall status of a payment intent. The status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).
succeeded, failed, cancelled, cancelled_post_capture, processing, requires_customer_action, requires_merchant_action, requires_payment_method, requires_confirmation, requires_capture, partially_captured, partially_captured_and_capturable, partially_authorized_and_requires_capture, partially_captured_and_processing, conflicted, expired This Unit struct represents MinorUnit in which core amount works
The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
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 A type for profile_id that can be used for business profile ids
Identifier for Payment Method
"pm_01926c58bc6e77c09e809964e72af8c8"
The url to which user must be redirected to after completion of the purchase
Contains the url for redirection flow
To indicate the type of payment experience that the customer would go through
redirect_to_url, invoke_sdk_client, display_qr_code, one_click, link_wallet, invoke_payment_app, display_wait_screen, collect_otp Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.
ach, affirm, afterpay_clearpay, alfamart, ali_pay, ali_pay_hk, alma, amazon_pay, paysera, apple_pay, atome, bacs, bancontact_card, becs, benefit, bizum, blik, bluecode, boleto, bca_bank_transfer, bni_va, breadpay, bri_va, bhn_card_network, card_redirect, cimb_va, classic, credit, crypto_currency, cashapp, dana, danamon_va, debit, duit_now, efecty, eft, eps, flexiti, fps, evoucher, giropay, givex, google_pay, go_pay, gcash, ideal, interac, indomaret, klarna, kakao_pay, local_bank_redirect, mandiri_va, knet, mb_way, mobile_pay, momo, momo_atm, multibanco, online_banking_thailand, online_banking_czech_republic, online_banking_finland, online_banking_fpx, online_banking_poland, online_banking_slovakia, oxxo, pago_efectivo, permata_bank_transfer, open_banking_uk, pay_bright, payjustnow, paypal, paze, pix, pay_safe_card, przelewy24, prompt_pay, pse, red_compra, red_pagos, samsung_pay, sepa, sepa_bank_transfer, sepa_guarenteed_debit, skrill, sofort, swish, touch_n_go, trustly, twint, upi_collect, upi_intent, upi_qr, vipps, viet_qr, venmo, walley, we_chat_pay, seven_eleven, lawson, mini_stop, family_mart, seicomart, pay_easy, local_bank_transfer, mifinity, open_banking_pis, direct_carrier_billing, instant_bank_transfer, instant_bank_transfer_finland, instant_bank_transfer_poland, revolut_pay, indonesian_bank_transfer, open_banking This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK
Show child attributes
Show child attributes
Address details
Show child attributes
Show child attributes
The city, district, suburb, town, or village of the address.
50"New York"
AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, US The first line of the street address or P.O. Box.
200"123, King Street"
The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).
50"Powelson Avenue"
The third line of the street address, if applicable.
50"Bridgewater"
The zip/postal code for the address
50"08807"
The address state
"New York"
The first name for the address
255"John"
The last name for the address
255"Doe"
The zip/postal code of the origin
50"08807"
Show child attributes
Show child attributes
Address details
Show child attributes
Show child attributes
The city, district, suburb, town, or village of the address.
50"New York"
AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, US The first line of the street address or P.O. Box.
200"123, King Street"
The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).
50"Powelson Avenue"
The third line of the street address, if applicable.
50"Bridgewater"
The zip/postal code for the address
50"08807"
The address state
"New York"
The first name for the address
255"John"
The last name for the address
255"Doe"
The zip/postal code of the origin
50"08807"
The type of the payment that differentiates between normal and various types of mandate payments. Use 'setup_mandate' in case of zero auth flow.
normal, new_mandate, setup_mandate, recurring_mandate "token_sxJdmpUnpNsJk5VWzcjl"
Show child attributes
Show child attributes
A type for invoice_id that can be used for invoice ids
A type for subscription_id that can be used for subscription ids
A type for merchant_id that can be used for merchant ids
A type for profile_id that can be used for business profile ids
A type for merchant_connector_id that can be used for merchant_connector_account ids
A type for customer_id that can be used for customer ids
This Unit struct represents MinorUnit in which core amount works
The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
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 invoice_created, payment_pending, payment_pending_timeout, payment_succeeded, payment_failed, payment_canceled, invoice_paid, manual_review, voided A type for payment_id that can be used for payment ids
Identifier for Payment Method
"pm_01926c58bc6e77c09e809964e72af8c8"
billing processor invoice id
Was this page helpful?