Payment Method - Create Intent

POST /v2/payment-methods/create-intent

Description: Create a payment method intent.

---

Example request (cURL)

curl

curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payment-methods/create-intent \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "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>"
  }
}
'

---

Example response (200)

application/json

{
  "id": "12345_pm_01926c58bc6e77c09e809964e72af8c8",
  "merchant_id": "merchant_1671528864",
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "recurring_enabled": true,
  "created": "2023-01-18T11:04:09.922Z",
  "last_used_at": "2024-02-24T11:04:09.922Z",
  "payment_method_data": {
    "card": {
      "saved_to_locker": true,
      "issuer_country": "AF",
      "last4_digits": "4242",
      "expiry_month": "10",
      "expiry_year": "25",
      "card_holder_name": "John Doe",
      "card_fingerprint": "fingerprint_12345",
      "nick_name": "Card",
      "card_network": "Visa",
      "card_isin": "4567890",
      "card_issuer": "Issuer Bank",
      "card_type": "Credit"
    }
  },
  "connector_tokens": [
    {
      "token": "pm_9UhMqBMEOooRIvJFFdeW",
      "connector_token_request_reference_id": "<string>"
    }
  ],
  "network_token": {
    "payment_method_data": {
      "last4_digits": "4242",
      "issuer_country": "AF",
      "network_token_expiry_month": "05",
      "network_token_expiry_year": "27",
      "nick_name": "Card",
      "card_holder_name": "John Doe",
      "card_isin": "16712672",
      "card_issuer": "Bank of America",
      "card_network": "Visa",
      "card_type": "Credit",
      "saved_to_locker": true
    }
  },
  "storage_type": "volatile",
  "card_cvc_token_storage": {
    "is_stored": true,
    "expires_at": "2024-02-24T11:04:09.922Z"
  }
}

---

Authorizations

• api-key (header) — 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)

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

• metadata (object) You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

• billing (object) Billing information (shows child attributes in the API source).

---

Response (200) — Payment Method Intent Created

Response fields (selected):

• id (string) — required The 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. Required string length: 32 - 64

• payment_method_type (enum) — required Indicates the type of payment method. Eg: 'card', 'wallet', etc. Available options include: 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, etc.

• payment_method_subtype (enum) Indicates the sub type of payment method (e.g., 'google_pay', 'apple_pay' for wallets). Available options include many subtypes such as ach, apple_pay, google_pay, paypal, sepa, venmo, network_token, etc.

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

• created (string | null) Timestamp (ISO 8601) of creation. Example: "2023-01-18T11:04:09.922Z"

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

• payment_method_data (object) Object containing payment-method specific data (e.g., card details).

• connector_tokens (object[] | null) The connector token details if available.

• network_token (object) Network token details (shows child attributes in the API source).

• storage_type (enum) Options: volatile, persistent

• card_cvc_token_storage (object) Details about CVC token storage (shows child attributes in the API source).

---

Related links:

• Documentation: https://api-reference.hyperswitch.io/introduction

• Locker API Reference: https://api-reference.hyperswitch.io/locker-api-reference/overview

• Intelligent Router API Reference: https://api-reference.hyperswitch.io/intelligent-router-api-reference/overview

• Source file for edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/payment-methods/payment-method--create-intent.mdx

• Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v2/payment-methods/payment-method--create-intent

Related endpoints:

• Payment Method - Create: https://api-reference.hyperswitch.io/v2/payment-methods/payment-method--create

• Payment Method - Confirm Intent: https://api-reference.hyperswitch.io/v2/payment-methods/payment-method--confirm-intent