Authentication - Create
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": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1",
"tax_registration_id": "<string>",
"document_details": {
"document_number": "12345678911"
},
"date_of_birth": "1990-01-31"
}
}
'import requests
url = "https://sandbox.hyperswitch.io/authentication"
payload = {
"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": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1",
"tax_registration_id": "<string>",
"document_details": { "document_number": "12345678911" },
"date_of_birth": "1990-01-31"
}
}
headers = {
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: 'johntest@test.com',
phone: '9123456789',
phone_country_code: '+1',
tax_registration_id: '<string>',
document_details: {document_number: '12345678911'},
date_of_birth: '1990-01-31'
}
})
};
fetch('https://sandbox.hyperswitch.io/authentication', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.hyperswitch.io/authentication",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => 'johntest@test.com',
'phone' => '9123456789',
'phone_country_code' => '+1',
'tax_registration_id' => '<string>',
'document_details' => [
'document_number' => '12345678911'
],
'date_of_birth' => '1990-01-31'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.hyperswitch.io/authentication"
payload := strings.NewReader("{\n \"amount\": 123,\n \"authentication_id\": \"auth_mbabizu24mvu3mela5njyhpit4\",\n \"profile_id\": \"<string>\",\n \"return_url\": \"https://example.com/redirect\",\n \"force_3ds_challenge\": true,\n \"profile_acquirer_id\": \"<string>\",\n \"acquirer_details\": {\n \"acquirer_bin\": \"123456\",\n \"acquirer_merchant_id\": \"merchant_abc\",\n \"merchant_country_code\": \"US/34456\"\n },\n \"customer_details\": {\n \"id\": \"cus_y3oqhf46pyzuxjbcn2giaqnb44\",\n \"name\": \"John Doe\",\n \"email\": \"johntest@test.com\",\n \"phone\": \"9123456789\",\n \"phone_country_code\": \"+1\",\n \"tax_registration_id\": \"<string>\",\n \"document_details\": {\n \"document_number\": \"12345678911\"\n },\n \"date_of_birth\": \"1990-01-31\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.hyperswitch.io/authentication")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 123,\n \"authentication_id\": \"auth_mbabizu24mvu3mela5njyhpit4\",\n \"profile_id\": \"<string>\",\n \"return_url\": \"https://example.com/redirect\",\n \"force_3ds_challenge\": true,\n \"profile_acquirer_id\": \"<string>\",\n \"acquirer_details\": {\n \"acquirer_bin\": \"123456\",\n \"acquirer_merchant_id\": \"merchant_abc\",\n \"merchant_country_code\": \"US/34456\"\n },\n \"customer_details\": {\n \"id\": \"cus_y3oqhf46pyzuxjbcn2giaqnb44\",\n \"name\": \"John Doe\",\n \"email\": \"johntest@test.com\",\n \"phone\": \"9123456789\",\n \"phone_country_code\": \"+1\",\n \"tax_registration_id\": \"<string>\",\n \"document_details\": {\n \"document_number\": \"12345678911\"\n },\n \"date_of_birth\": \"1990-01-31\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hyperswitch.io/authentication")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 123,\n \"authentication_id\": \"auth_mbabizu24mvu3mela5njyhpit4\",\n \"profile_id\": \"<string>\",\n \"return_url\": \"https://example.com/redirect\",\n \"force_3ds_challenge\": true,\n \"profile_acquirer_id\": \"<string>\",\n \"acquirer_details\": {\n \"acquirer_bin\": \"123456\",\n \"acquirer_merchant_id\": \"merchant_abc\",\n \"merchant_country_code\": \"US/34456\"\n },\n \"customer_details\": {\n \"id\": \"cus_y3oqhf46pyzuxjbcn2giaqnb44\",\n \"name\": \"John Doe\",\n \"email\": \"johntest@test.com\",\n \"phone\": \"9123456789\",\n \"phone_country_code\": \"+1\",\n \"tax_registration_id\": \"<string>\",\n \"document_details\": {\n \"document_number\": \"12345678911\"\n },\n \"date_of_birth\": \"1990-01-31\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1",
"tax_registration_id": "<string>",
"document_details": {
"document_type": "cpf",
"document_number": "12345678911"
},
"date_of_birth": "1990-01-31"
}
}Authentication
Authentication - Create
Create a new authentication for accessing our APIs from your servers.
POST
/
authentication
Authentication - Create
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": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1",
"tax_registration_id": "<string>",
"document_details": {
"document_number": "12345678911"
},
"date_of_birth": "1990-01-31"
}
}
'import requests
url = "https://sandbox.hyperswitch.io/authentication"
payload = {
"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": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1",
"tax_registration_id": "<string>",
"document_details": { "document_number": "12345678911" },
"date_of_birth": "1990-01-31"
}
}
headers = {
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: 'johntest@test.com',
phone: '9123456789',
phone_country_code: '+1',
tax_registration_id: '<string>',
document_details: {document_number: '12345678911'},
date_of_birth: '1990-01-31'
}
})
};
fetch('https://sandbox.hyperswitch.io/authentication', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.hyperswitch.io/authentication",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => 'johntest@test.com',
'phone' => '9123456789',
'phone_country_code' => '+1',
'tax_registration_id' => '<string>',
'document_details' => [
'document_number' => '12345678911'
],
'date_of_birth' => '1990-01-31'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.hyperswitch.io/authentication"
payload := strings.NewReader("{\n \"amount\": 123,\n \"authentication_id\": \"auth_mbabizu24mvu3mela5njyhpit4\",\n \"profile_id\": \"<string>\",\n \"return_url\": \"https://example.com/redirect\",\n \"force_3ds_challenge\": true,\n \"profile_acquirer_id\": \"<string>\",\n \"acquirer_details\": {\n \"acquirer_bin\": \"123456\",\n \"acquirer_merchant_id\": \"merchant_abc\",\n \"merchant_country_code\": \"US/34456\"\n },\n \"customer_details\": {\n \"id\": \"cus_y3oqhf46pyzuxjbcn2giaqnb44\",\n \"name\": \"John Doe\",\n \"email\": \"johntest@test.com\",\n \"phone\": \"9123456789\",\n \"phone_country_code\": \"+1\",\n \"tax_registration_id\": \"<string>\",\n \"document_details\": {\n \"document_number\": \"12345678911\"\n },\n \"date_of_birth\": \"1990-01-31\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.hyperswitch.io/authentication")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 123,\n \"authentication_id\": \"auth_mbabizu24mvu3mela5njyhpit4\",\n \"profile_id\": \"<string>\",\n \"return_url\": \"https://example.com/redirect\",\n \"force_3ds_challenge\": true,\n \"profile_acquirer_id\": \"<string>\",\n \"acquirer_details\": {\n \"acquirer_bin\": \"123456\",\n \"acquirer_merchant_id\": \"merchant_abc\",\n \"merchant_country_code\": \"US/34456\"\n },\n \"customer_details\": {\n \"id\": \"cus_y3oqhf46pyzuxjbcn2giaqnb44\",\n \"name\": \"John Doe\",\n \"email\": \"johntest@test.com\",\n \"phone\": \"9123456789\",\n \"phone_country_code\": \"+1\",\n \"tax_registration_id\": \"<string>\",\n \"document_details\": {\n \"document_number\": \"12345678911\"\n },\n \"date_of_birth\": \"1990-01-31\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hyperswitch.io/authentication")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 123,\n \"authentication_id\": \"auth_mbabizu24mvu3mela5njyhpit4\",\n \"profile_id\": \"<string>\",\n \"return_url\": \"https://example.com/redirect\",\n \"force_3ds_challenge\": true,\n \"profile_acquirer_id\": \"<string>\",\n \"acquirer_details\": {\n \"acquirer_bin\": \"123456\",\n \"acquirer_merchant_id\": \"merchant_abc\",\n \"merchant_country_code\": \"US/34456\"\n },\n \"customer_details\": {\n \"id\": \"cus_y3oqhf46pyzuxjbcn2giaqnb44\",\n \"name\": \"John Doe\",\n \"email\": \"johntest@test.com\",\n \"phone\": \"9123456789\",\n \"phone_country_code\": \"+1\",\n \"tax_registration_id\": \"<string>\",\n \"document_details\": {\n \"document_number\": \"12345678911\"\n },\n \"date_of_birth\": \"1990-01-31\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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": "johntest@test.com",
"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
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
This Unit struct represents MinorUnit in which core amount works
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 The unique identifier for this authentication.
Example:
"auth_mbabizu24mvu3mela5njyhpit4"
The business profile that is associated with this authentication
Available options:
threedsecureio, netcetera, gpayments, ctp_mastercard, unified_authentication_service, juspaythreedsserver, ctp_visa, cardinal The URL to which the user should be redirected after authentication.
Example:
"https://example.com/redirect"
Force 3DS challenge.
SCA Exemptions types available for authentication
Available options:
low_value, transaction_risk_analysis Profile Acquirer ID get from profile acquirer configuration
Show child attributes
Show child attributes
Passing this object creates a new customer or attaches an existing customer to the payment
Show child attributes
Show child attributes
Response
Authentication created
The unique identifier for this authentication.
Example:
"auth_mbabizu24mvu3mela5njyhpit4"
This is an identifier for the merchant account. This is inferred from the API key provided during the request
Example:
"merchant_abc"
Available options:
started, pending, success, failed This Unit struct represents MinorUnit in which core amount works
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 The client secret for this authentication, to be used for client-side operations.
Example:
"auth_mbabizu24mvu3mela5njyhpit4_secret_el9ksDkiB8hi6j9N78yo"
Available options:
threedsecureio, netcetera, gpayments, ctp_mastercard, unified_authentication_service, juspaythreedsserver, ctp_visa, cardinal Whether 3DS challenge was forced.
The URL to which the user should be redirected after authentication, if provided.
Example:
"2022-09-10T10:11:12Z"
Example:
"E0001"
If there was an error while calling the connector the error message is received here
Example:
"Failed while verifying the card"
The business profile that is associated with this payment
SCA Exemptions types available for authentication
Available options:
low_value, transaction_risk_analysis Show child attributes
Show child attributes
Profile Acquirer ID get from profile acquirer configuration
Passing this object creates a new customer or attaches an existing customer to the payment
Show child attributes
Show child attributes