Payment Method - Create

POST https://sandbox.hyperswitch.io/v2/payment-methods

Try it

Example request (cURL)

curl
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_data": {
    "card": {
      "card_number": "4111111145551142",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "John Doe",
      "card_issuing_country": "AF",
      "card_cvc": "242",
      "nick_name": "John Doe",
      "card_network": "Visa",
      "card_issuer": "<string>",
      "card_type": "credit"
    }
  },
  "metadata": {},
  "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>"
  },
  "psp_tokenization": {
    "tokenization_type": "single_use",
    "connector_id": "mca_28a7367sad8239s67"
  },
  "network_tokenization": {
    "enable": "Enable"
  },
  "storage_type": "volatile"
}
'

Example response (200)

Authorization

Header: api-key (string) — required

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.

Request body (application/json)

  • payment_method_type (string, enum) — required Indicates the type of payment method. Example: "card", "wallet", etc.

    Available options (summary):

    • 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_subtype (string, enum) — required Indicates the sub type of payment method. Example: 'google_pay' & 'apple_pay' for wallets.

  • customer_id (string) — required The unique identifier of the customer. Required string length: 32 - 64 Example: "12345_cus_01926c58bc6e77c09e809964e72af8c8"

  • payment_method_data (object) — required Contains the payment method details (e.g., card object with number, expiry, etc.). See example request.

  • metadata (object) — optional Up to 50 keys; key names up to 40 chars; values up to 500 chars. Useful for storing additional structured information.

  • billing (object) — optional Contains billing address, phone, email. See example request.

  • psp_tokenization (object) — optional Payment Service Provider configuration for payment methods created using the payment method session. Example fields shown in request.

  • network_tokenization (object) — optional Network tokenization configuration for creating the payment method session.

  • storage_type (string, enum) — optional Available options: volatile, persistent

Response (200 — Payment Method Created)

Response fields:

  • id (string) — required Unique identifier of the Payment method. Example: "12345_pm_01926c58bc6e77c09e809964e72af8c8"

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

  • customer_id (string) — required The unique identifier of the customer. Example: "12345_cus_01926c58bc6e77c09e809964e72af8c8"

  • payment_method_type (string, enum) — required See request section for available types.

  • payment_method_subtype (string, enum) See request section for available subtypes.

  • recurring_enabled (boolean | null) Indicates whether the payment method supports recurring payments. Example: true

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

  • last_used_at (string, date-time | null) ISO 8601 timestamp when the payment method was last used. Example: "2024-02-24T11:04:09.922Z"

  • payment_method_data (object) Payment method details (e.g., card info). See example response.

  • connector_tokens (array | null) Connector token details if available.network_token (object) Network token details if available.storage_type (string) volatile or persistentcard_cvc_token_storage (object) Indicates CVC token storage status and expiry (if applicable).Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/payment-methods/payment-method--create.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v2/payment-methods/payment-method--create

PreviousPayouts - ListNextPayouts - Fulfill