Authentication - Create

POST /authentication

Create an authentication.

cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/authentication \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "amount": 123,
  "currency": "AED",
  "authentication_id": "auth_mbabizu24mvu3mela5njyhpit4",
  "profile_id": "<string>",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "<string>"
  },
  "authentication_connector": "threedsecureio",
  "return_url": "https://example.com/redirect",
  "force_3ds_challenge": true,
  "psd2_sca_exemption_type": "low_value",
  "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": "[email protected]",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "<string>"
  }
}
'

Example response (200)

Authorization (header)

  • Name: api-key

  • In: header

  • Type: string

  • Required: yes

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)

  • amount (integer) — required This Unit struct represents MinorUnit in which core amount works.

  • currency (enum) — 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.

  • customer (object) Passing this object creates a new customer or attaches an existing customer to the payment. Child attributes shown in API docs (id, name, email, phone, phone_country_code, tax_registration_id).

  • authentication_connector (enum) 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) SCA Exemptions types available for authentication. Available options: low_value, transaction_risk_analysis

  • profile_acquirer_id (string | null) Profile Acquirer ID obtained from profile acquirer configuration.

  • acquirer_details (object) Child attributes shown in API docs (acquirer_bin, acquirer_merchant_id, merchant_country_code).

  • customer_details (object) Passing this object creates a new customer or attaches an existing customer to the payment. Child attributes shown in API docs.

Response (200 — application/json)

Authentication created. Fields:

  • authentication_id (string) — required The unique identifier for this authentication. Example: "auth_mbabizu24mvu3mela5njyhpit4"

  • merchant_id (string) — required Identifier for the merchant account inferred from the API key. Example: "merchant_abc"

  • status (enum) — required Available options: started, pending, success, failed

  • amount (integer) — required Minor unit amount.

  • currency (enum) — required Three-letter ISO 4217 currency code. (Same full list as in request currency.)

  • 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) Connector used. 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 | 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 associated with this payment.

  • psd2_sca_exemption_type (enum) low_value, transaction_risk_analysis

  • acquirer_details (object) Child attributes shown in API docs.

  • profile_acquirer_id (string | null) Profile Acquirer ID from profile acquirer configuration.

  • customer_details (object) Passing this object creates a new customer or attaches an existing customer to the payment. Child attributes shown in API docs.

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/authentication/authentication--create.mdx Raise an issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/authentication/authentication--create

PreviousAuthentication - POST Eligibility CheckNextrouting