Payment Method Session - Create

Create a payment method session.

POST /v2/payment-method-sessions

Request example (cURL):

Create Payment Method Session (cURL)
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payment-method-sessions \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "expires_in": 900
}
'

Successful response (200):

Response (application/json)
{
  "id": "12345_pms_01926c58bc6e77c09e809964e72af8c8",
  "expires_at": "2023-01-18T11:04:09.922Z",
  "client_secret": "cs_9wcXDRVkfEtLEsSnYKgQ",
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "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"
  },
  "tokenization_data": "<unknown>",
  "return_url": "https://merchant-website.com/return",
  "next_action": {
    "redirect_to_url": "https://example.com/redirect",
    "type": "redirect_to_url"
  },
  "authentication_details": {
    "status": "succeeded",
    "error": {
      "code": "card_declined",
      "message": "The card was declined.",
      "reason": "The card was declined.",
      "unified_code": "card_declined",
      "unified_message": "The card was declined.",
      "network_advice_code": "01",
      "network_decline_code": "05",
      "network_error_message": "Do not retry"
    }
  },
  "associated_payment_methods": [
    {
      "payment_method_token": {
        "type": "payment_method_session_token",
        "data": "token_9wcXDRVkfEtLEsSnYKgQ"
      }
    }
  ],
  "associated_token_id": "12345_tok_01926c58bc6e77c09e809964e72af8c8",
  "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.

Related link: https://api-reference.hyperswitch.io/

Request body (application/json)

  • customer_id — string | null The customer id for which the payment methods session is to be created. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

  • billing — object Billing details (address, phone, email). See response example for shape.

  • return_url — string | null The return url to which the customer should be redirected to after adding the payment method.

  • psp_tokenization — object The Payment Service Provider configuration for payment methods created using the payment method session.

  • network_tokenization — object The network tokenization configuration for creating the payment method session.

  • expires_in — integer (int32) | null — default: 900 The time in seconds when the session will expire. If not provided, the session will expire in 15 minutes. Required range: x >= 0 Example: 900

  • tokenization_data — any | null Contains data to be passed to tokenization service (if present) to create token_id for given JSON data.

Response (200, application/json)

The response returns the created payment method session and related data. Notable fields:

  • id — string (required) Example: "12345_pms_01926c58bc6e77c09e809964e72af8c8"

  • expires_at — string (date-time) (required) ISO timestamp when the session will expire. Trying to retrieve the session or perform operations after this time will result in an error. Example: "2023-01-18T11:04:09.922Z"

  • client_secret — string (required) Client Secret. Example: "cs_9wcXDRVkfEtLEsSnYKgQ"

  • customer_id — string | null The customer id for which the payment methods session is created.

  • billing — object Billing details (address, phone, email).

  • psp_tokenization — object Payment Service Provider configuration for methods created using this session.

  • network_tokenization — object Network tokenization configuration for session.

  • tokenization_data — any | null Data passed to tokenization service (if present).

  • return_url — string | null The return url to which the user should be redirected. Example: "https://merchant-website.com/return"

  • next_action — object Contains URL for any redirect flow, e.g. { "redirect_to_url": "...", "type": "redirect_to_url" }

  • authentication_details — object Authentication result and any error details (see response example).

  • associated_payment_methods — object[] | null The payment methods created using this payment method session.

  • associated_token_id — string | null The token-id created if tokenization_data was present. Example: "12345_tok_01926c58bc6e77c09e809964e72af8c8"

  • storage_type — enum Available options: volatile, persistent

  • card_cvc_token_storage — object Information about CVC token storage (is_stored, expires_at).

Related:

  • Check network token status: https://api-reference.hyperswitch.io/v2/payment-methods/check-network-token-status

  • Payment Method Session — Retrieve: https://api-reference.hyperswitch.io/v2/payment-method-session/payment-method-session--retrieve

Edit or raise issues:

  • Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/payment-method-session/payment-method-session--create.mdx

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

PreviousPayment Method Session - RetrieveNextMerchant Account - Create