PaymentMethods - Create

POST /payment_methods

Try it: https://sandbox.hyperswitch.io/payment_methods

Example request (cURL)

Create Payment Method — cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/payment_methods \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "card": {
    "card_exp_month": "11",
    "card_exp_year": "25",
    "card_holder_name": "John Doe",
    "card_number": "4242424242424242"
  },
  "customer_id": "{{customer_id}}",
  "payment_method": "card",
  "payment_method_issuer": "Visa",
  "payment_method_type": "credit"
}
'

Example response (200)

200 — Payment Method Created

{
  "merchant_id": "merchant_1671528864",
  "payment_method_id": "card_rGK4Vi5iSW70MY7J2mIg",
  "payment_method": "card",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "payment_method_type": "ach",
  "card": {
    "saved_to_locker": true,
    "scheme": "<string>",
    "issuer_country": "<string>",
    "issuer_country_code": "<string>",
    "last4_digits": "<string>",
    "expiry_month": "<string>",
    "expiry_year": "<string>",
    "card_token": "<string>",
    "card_holder_name": "<string>",
    "card_fingerprint": "<string>",
    "nick_name": "<string>",
    "card_network": "Visa",
    "card_isin": "<string>",
    "card_issuer": "<string>",
    "card_type": "<string>"
  },
  "recurring_enabled": true,
  "installment_payment_enabled": true,
  "payment_experience": [
    "redirect_to_url"
  ],
  "metadata": {},
  "created": "2023-01-18T11:04:09.922Z",
  "bank_transfer": {
    "bank_account_number": "000123456",
    "bank_routing_number": "110000000",
    "bank_name": "Deutsche Bank",
    "bank_country_code": "AF",
    "bank_city": "California"
  },
  "last_used_at": "2024-02-24T11:04:09.922Z",
  "client_secret": "<string>"
}

---

Authorizations

• api-key (header, required) — string

Use the API key created under your merchant account from the HyperSwitch dashboard. The API key authenticates API requests from your merchant server only. Do not expose this key on a website or embed it in a mobile application.

---

Body (application/json)

Fields:

• payment_method (string, required) — Indicates the type of payment method. Example: "card".

• payment_method_type (string) — Indicates the sub type of payment method (e.g., "google_pay", "apple_pay").

• payment_method_issuer (string | null) — The name of the bank/provider issuing the payment method to the end user. Example: "Citibank".

• payment_method_issuer_code (string) — Issuer code (available options listed below).

• card (object) — Card attributes (see child attributes).

• bank_transfer (object) — Bank transfer attributes (see child attributes).

• wallet (object) — Wallet attributes (see child attributes).

• payment_method_data (object) — Connector-specific data (see child attributes).

• billing (object) — Billing details (see child attributes).

• metadata (object) — Up to 50 keys; key names up to 40 chars; values up to 500 chars.

• customer_id (string | null) — Unique identifier of the customer. Required string length: 1–64. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44".

• card_network (string | null) — The card network. Example: "Visa".

• client_secret (string | null) — For client-based calls; SDK will use this client_secret. It is generated whenever a new payment method is created.

Expandable: available enums and long lists

payment_method — Available options

card, card_redirect, pay_later, wallet, bank_redirect, bank_transfer, crypto, bank_debit, reward, real_time_payment, upi, voucher, gift_card, open_banking, mobile_payment, network_token

payment_method_type — Available options (long list)

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, network_token

payment_method_issuer_code — Available options

jp_hdfc, jp_icici, jp_googlepay, jp_applepay, jp_phonepay, jp_wechat, jp_sofort, jp_giropay, jp_sepa, jp_bacs

---

Response (200 — application/json)

Payment Method Created — fields:

• merchant_id (string, required) — Unique identifier for a merchant. Example: "merchant_1671528864".

• payment_method_id (string, required) — Unique identifier of the payment method. Example: "card_rGK4Vi5iSW70MY7J2mIg".

• payment_method (string, required) — Type of payment method (see payment_method available options above).

• customer_id (string | null) — Unique identifier of the customer. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44".

• payment_method_type (string) — Sub type of payment method (see payment_method_type list above).

• card (object) — Card attributes (child attributes shown in example response).

• recurring_enabled (boolean | null) — Whether supports recurring payments. Example: true.

• installment_payment_enabled (boolean | null) — Eligible for installment payments. Example: true.

• payment_experience (string[] | null) — Type of payment experience enabled with the connector. Example: ["redirect_to_url"].

• metadata (object) — Up to 50 keys; key names up to 40 chars; values up to 500 chars.

• created (string | null) — ISO 8601 timestamp when the payment method was created. Example: "2023-01-18T11:04:09.922Z".

• bank_transfer (object) — Bank transfer attributes (child attributes shown in example response).

• last_used_at (string | null) — Example: "2024-02-24T11:04:09.922Z".

• client_secret (string | null) — For client-based calls.

---

Child objects

• card (object): saved_to_locker, scheme, issuer_country, issuer_country_code, last4_digits, expiry_month, expiry_year, card_token, card_holder_name, card_fingerprint, nick_name, card_network, card_isin, card_issuer, card_type, etc.

• bank_transfer (object): bank_account_number, bank_routing_number, bank_name, bank_country_code, bank_city, etc.

• wallet (object): connector-specific wallet fields.

• payment_method_data (object): connector-specific data.

• billing (object): billing address and related fields.

---

Was this page helpful?

• Yes / No

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/payment-methods/paymentmethods--create.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/payment-methods/paymentmethods--create

Related:

• Payments - Submit Eligibility Data: https://api-reference.hyperswitch.io/v1/payments/payments--submit-eligibility-data

• Payment Method - Retrieve: https://api-reference.hyperswitch.io/v1/payment-methods/payment-method--retrieve