Payment Method Session - Create

Authorizations

api-key

string

header

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.

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

Show child attributes

billing.address

object

Address details

Show child attributes

billing.address.city

string | null

The city, district, suburb, town, or village of the address.

Maximum string length: 50

Example:

"New York"

billing.address.country

enum<string>

Available options:

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

billing.address.line1

string | null

The first line of the street address or P.O. Box.

Maximum string length: 200

Example:

"123, King Street"

billing.address.line2

string | null

The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).

Maximum string length: 50

Example:

"Powelson Avenue"

billing.address.line3

string | null

The third line of the street address, if applicable.

Maximum string length: 50

Example:

"Bridgewater"

billing.address.zip

string | null

The zip/postal code for the address

Maximum string length: 50

Example:

"08807"

billing.address.state

string | null

The address state

Example:

"New York"

billing.address.first_name

string | null

The first name for the address

Maximum string length: 255

Example:

"John"

billing.address.last_name

string | null

The last name for the address

Maximum string length: 255

Example:

"Doe"

billing.address.origin_zip

string | null

The zip/postal code of the origin

Maximum string length: 50

Example:

"08807"

billing.phone

object

Show child attributes

billing.phone.number

string | null

The contact number

Example:

"9123456789"

billing.phone.country_code

string | null

The country code attached to the number

Example:

"+1"

billing.email

string | null

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 that are created using the payment method session

Show child attributes

psp_tokenization.tokenization_type

enum<string>

required

The type of tokenization to use for the payment method

Available options:

single_use,

multi_use

psp_tokenization.connector_id

string

required

The merchant connector id to be used for tokenization

network_tokenization

object

The network tokenization configuration for creating the payment method session

Show child attributes

network_tokenization.enable

enum<string>

required

The network tokenization toggle, whether to enable or skip the network tokenization

Available options:

Enable,

Skip

expires_in

integer<int32> | null

default:900

The time (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 on to tokenization service ( if present ) to create token_id for given JSON data

Response

Create the payment method session

string

required

Example:

"12345_pms_01926c58bc6e77c09e809964e72af8c8"

expires_at

string<date-time>

required

The iso timestamp when the session will expire Trying to retrieve the session or any operations on the session after this time will result in an error

Example:

"2023-01-18T11:04:09.922Z"

client_secret

string

required

Client Secret

customer_id

string | null

The customer id for which the payment methods session is to be created

Example:

"12345_cus_01926c58bc6e77c09e809964e72af8c8"

billing

object

Show child attributes

billing.address

object

Address details

Show child attributes

billing.address.city

string | null

The city, district, suburb, town, or village of the address.

Maximum string length: 50

Example:

"New York"

billing.address.country

enum<string>

Available options:

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

billing.address.line1

string | null

The first line of the street address or P.O. Box.

Maximum string length: 200

Example:

"123, King Street"

billing.address.line2

string | null

The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).

Maximum string length: 50

Example:

"Powelson Avenue"

billing.address.line3

string | null

The third line of the street address, if applicable.

Maximum string length: 50

Example:

"Bridgewater"

billing.address.zip

string | null

The zip/postal code for the address

Maximum string length: 50

Example:

"08807"

billing.address.state

string | null

The address state

Example:

"New York"

billing.address.first_name

string | null

The first name for the address

Maximum string length: 255

Example:

"John"

billing.address.last_name

string | null

The last name for the address

Maximum string length: 255

Example:

"Doe"

billing.address.origin_zip

string | null

The zip/postal code of the origin

Maximum string length: 50

Example:

"08807"

billing.phone

object

Show child attributes

billing.phone.number

string | null

The contact number

Example:

"9123456789"

billing.phone.country_code

string | null

The country code attached to the number

Example:

"+1"

billing.email

string | null

psp_tokenization

object

The Payment Service Provider Configuration for payment methods that are created using the payment method session

Show child attributes

psp_tokenization.tokenization_type

enum<string>

required

The type of tokenization to use for the payment method

Available options:

single_use,

multi_use

psp_tokenization.connector_id

string

required

The merchant connector id to be used for tokenization

network_tokenization

object

The network tokenization configuration for creating the payment method session

Show child attributes

network_tokenization.enable

enum<string>

required

The network tokenization toggle, whether to enable or skip the network tokenization

Available options:

Enable,

Skip

tokenization_data

any | null

Contains data to be passed on to tokenization service ( if present ) to create token_id for given JSON data

return_url

string | null

The return url to which the user should be redirected to

next_action

object

Contains the url for redirection flow

Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Option 7
Option 8
Option 9
Option 10
Option 11
Option 12
Option 13

Show child attributes

next_action.redirect_to_url

string

required

next_action.type

enum<string>

required

Available options:

redirect_to_url

authentication_details

object

Show child attributes

authentication_details.status

enum<string>

required

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).

Available options:

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

authentication_details.error

object

Error details for the payment

Show child attributes

authentication_details.error.code

string

required

The error code

authentication_details.error.message

string

required

The error message

authentication_details.error.reason

string | null

The detailed error reason that was returned by the connector.

authentication_details.error.unified_code

string | null

The unified error code across all connectors. This can be relied upon for taking decisions based on the error.

authentication_details.error.unified_message

string | null

The unified error message across all connectors. If there is a translation available, this will have the translated message

authentication_details.error.network_advice_code

string | null

This field can be returned for both approved and refused Mastercard payments. This code provides additional information about the type of transaction or the reason why the payment failed. If the payment failed, the network advice code gives guidance on if and when you can retry the payment.

authentication_details.error.network_decline_code

string | null

For card errors resulting from a card issuer decline, a brand specific 2, 3, or 4 digit code which indicates the reason the authorization failed.

authentication_details.error.network_error_message

string | null

A string indicating how to proceed with an network error if payment gateway provide one. This is used to understand the network error code better.

associated_payment_methods

string[] | null

The payment method that was created using this payment method session

associated_token_id

string | null

The token-id created if there is tokenization_data present

Example:

"12345_tok_01926c58bc6e77c09e809964e72af8c8"

Get Started [BETA]

Essentials [BETA]

Payments Core APIs [BETA]

Account management APIs [BETA]

Other APIs [BETA]

Payment Method Session - Create

Authorizations

Body

Response