Authentication - Create

Create a new authentication for accessing our APIs from your servers.

POST /authentication

Authentication - Create

cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/authentication \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "amount": 123,
  "authentication_id": "auth_mbabizu24mvu3mela5njyhpit4",
  "profile_id": "<string>",
  "return_url": "https://example.com/redirect",
  "force_3ds_challenge": true,
  "profile_acquirer_id": "<string>",
  "acquirer_details": {
    "acquirer_bin": "123456",
    "acquirer_merchant_id": "merchant_abc",
    "merchant_country_code": "US/34456"
  },
  "customer_details": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "[e-mail]",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "<string>",
    "document_details": {
      "document_number": "12345678911"
    },
    "date_of_birth": "1990-01-31"
  }
}
'

200

{
  "authentication_id": "auth_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_abc",
  "status": "started",
  "amount": 123,
  "currency": "AED",
  "client_secret": "auth_mbabizu24mvu3mela5njyhpit4_secret_el9ksDkiB8hi6j9N78yo",
  "authentication_connector": "threedsecureio",
  "force_3ds_challenge": true,
  "return_url": "<string>",
  "created_at": "2022-09-10T10:11:12Z",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "profile_id": "<string>",
  "psd2_sca_exemption_type": "low_value",
  "acquirer_details": {
    "acquirer_bin": "123456",
    "acquirer_merchant_id": "merchant_abc",
    "merchant_country_code": "US/34456"
  },
  "profile_acquirer_id": "<string>",
  "customer_details": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "[e-mail]",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "<string>",
    "document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    },
    "date_of_birth": "1990-01-31"
  }
}

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

amount · integer<int64> · required

This Unit struct represents MinorUnit in which core amount works

currency · enum<string> · required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available options: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL

authentication_id · string | null

The unique identifier for this authentication.

Example:

"auth_mbabizu24mvu3mela5njyhpit4"

profile_id · string | null

The business profile that is associated with this authentication

authentication_connector · enum<string> | null

Available options: threedsecureio, netcetera, gpayments, ctp_mastercard, unified_authentication_service, juspaythreedsserver, ctp_visa, cardinal

return_url · string | null

The URL to which the user should be redirected after authentication.

Example:

"https://example.com/redirect"

force_3ds_challenge · boolean | null

Force 3DS challenge.

psd2_sca_exemption_type · enum<string> | null

SCA Exemptions types available for authentication

Available options: low_value, transaction_risk_analysis

profile_acquirer_id · string | null

Profile Acquirer ID get from profile acquirer configuration

acquirer_details · object | null

Show child attributes

customer_details · object | null

Passing this object creates a new customer or attaches an existing customer to the payment

Show child attributes

Response

200

application/json

Authentication created

authentication_id · string · required

The unique identifier for this authentication.

Example:

"auth_mbabizu24mvu3mela5njyhpit4"

merchant_id · string · required

This is an identifier for the merchant account. This is inferred from the API key provided during the request

Example:

"merchant_abc"

status · enum<string> · required

Available options: started, pending, success, failed

amount · integer<int64> · required

This Unit struct represents MinorUnit in which core amount works

currency · enum<string> · required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available options: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL

client_secret · string | null

The client secret for this authentication, to be used for client-side operations.

Example:

"auth_mbabizu24mvu3mela5njyhpit4_secret_el9ksDkiB8hi6j9N78yo"

authentication_connector · enum<string> | null

Available options: threedsecureio, netcetera, gpayments, ctp_mastercard, unified_authentication_service, juspaythreedsserver, ctp_visa, cardinal

force_3ds_challenge · boolean | null

Whether 3DS challenge was forced.

return_url · string | null

The URL to which the user should be redirected after authentication, if provided.

created_at · string<date-time> | null

Example:

"2022-09-10T10:11:12Z"

error_code · string | null

Example:

"E0001"

error_message · string | null

If there was an error while calling the connector the error message is received here

Example:

"Failed while verifying the card"

profile_id · string | null

The business profile that is associated with this payment

psd2_sca_exemption_type · enum<string> | null

SCA Exemptions types available for authentication

Available options: low_value, transaction_risk_analysis

acquirer_details · object | null

Show child attributes

profile_acquirer_id · string | null

Profile Acquirer ID get from profile acquirer configuration

customer_details · object | null

Passing this object creates a new customer or attaches an existing customer to the payment

Show child attributes