description |
---|
Hyperswitch is designed to facilitate the integration and management of payment-related functionalities in a decoupled or headless architecture with flexibility to customize your payments experience. |
{% hint style="info" %} This section guides you through the integration of Hyperswitch Headless for both web and mobile clients {% endhint %}
Initialize Hyper
onto your app with your publishable key with the Hyper
constructor. You’ll use HyperLoader
which you can call to create a Headless Payment Session. To get a Publishable Key please find it here.
{% tabs %} {% tab title="HTML + JavaScript" %}
// Source Hyperloader on your HTML file using the <script /> tag
hyper = Hyper.init(YOUR_PUBLISHABLE_KEY);
{% endtab %}
{% tab title="Flutter" %}
// dependencies: flutter_hyperswitch: ^version_number
// run the following command to fetch and install the dependencies flutter pub get
import 'package:flutter_hyperswitch/flutter_hyperswitch.dart';
_hyper.init(HyperConfig(publishableKey: 'YOUR_PUBLISHABLE_KEY'));
{% endtab %} {% endtabs %}
Make a request to the endpoint on your server to create a new Payment. The clientSecret
returned by your endpoint is used to initialize the payment session.
{% hint style="danger" %} Important: Make sure to never share your API key with your client application as this could potentially compromise your security {% endhint %}
Initialize a Payment Session by passing the clientSecret to the initPaymentSession
{% tabs %} {% tab title="JavaScript" %}
paymentSession = hyper.initPaymentSession({
clientSecret: client_secret,
});
{% endtab %}
{% tab title="Flutter" %}
final params = PaymentMethodParams(clientSecret: 'YOUR_PAYMENT_INTENT_CLIENT_SECRET')
Session _sessionId = await hyper.initPaymentSession(params);
{% endtab %} {% endtabs %}
options (Required) | Description |
---|---|
clientSecret (string) |
Required. Required to use as the identifier of the payment. |
Using the paymentSession
object, the default customer payment method data can be fetched, using which you can craft your own payments experience. The paymentSession
object also exposes a confirmWithCustomerDefaultPaymentMethod
function, using which you can confirm and handle the payment session.
{% tabs %} {% tab title="JavaScript" %}
paymentMethodSession = await paymentSession.getCustomerSavedPaymentMethods();
if (paymentMethodSession.error) {
// handle the case where no default customer payment method is not present
} else {
// use the customer_default_saved_payment_method_data to fulfill your usecases (render UI)
const customer_default_saved_payment_method_data =
paymentMethodSession.getCustomerDefaultSavedPaymentMethodData();
}
//handle press for pay button
function handlePress() {
if (paymentMethodSession.error) {
// handle the case where no default customer payment method is not present
} else {
// use the confirmWithCustomerDefaultPaymentMethod function to confirm and handle the payment session response
const { error, status } = await
paymentMethodSession.
confirmWithCustomerDefaultPaymentMethod({
confirmParams: {
// Make sure to change this to your payment completion page
return_url: "https://example.com/complete"
},
// if you wish to redirect always, otherwise it is defaulted to "if_required"
redirect: "always",
});
// use error, status to complete the payment journey
if (error) {
if (error.message) {
// handle error messages
setMessage(error.message);
} else {
setMessage("An unexpected error occurred.");
}
}
if (status) {
// handle payment status
handlePaymentStatus(status);
}
}
}
{% endtab %}
{% tab title="Flutter" %}
SavedSession? _savedSessionId = await _hyper.getCustomerSavedPaymentMethods(_sessionId!);
// use the customer_default_saved_payment_method_data to fulfill your usecases
final customer_default_saved_payment_method_data = await _hyper.getCustomerDefaultSavedPaymentMethodData(_savedSessionId!);
if (customer_default_saved_payment_method_data != null) {
final paymentMethod = customer_default_saved_payment_method_data.left;
if (paymentMethod != null) {
final card = paymentMethod.left;
if (card != null) {
setState(() {
_defaultPMText = "${card.nickName} ${card.cardNumber} ${card.expiryDate}";
});
} else {
final wallet = paymentMethod.right;
if (wallet != null) {
setState(() {
_defaultPMText = wallet.walletType;
});
}
}
} else {
final err = customer_default_saved_payment_method_data.right;
setState(() {
_defaultPMText = err?.message ?? "No Default Payment Method present";
});
}
}
}
// use the confirmWithCustomerDefaultPaymentMethod function to confirm and handle the payment session response
Future<void> _confirmPayment() async {
final confirmWithCustomerDefaultPaymentMethodResponse =
await _hyper.confirmWithCustomerDefaultPaymentMethod(_savedSessionId!);
if (confirmWithCustomerDefaultPaymentMethodResponse != null) {
final message = confirmWithCustomerDefaultPaymentMethodResponse.message;
if (message.isLeft) {
_confirmStatusText = "${confirmWithCustomerDefaultPaymentMethodResponse.status.name}\n${message.left!.name}";
} else {
_confirmStatusText = "${confirmWithCustomerDefaultPaymentMethodResponse.status.name}\n${message.right}";
}
}
}
{% endtab %} {% endtabs %}
Payload for confirmWithCustomerDefaultPaymentMethod(payload)
options (Required) | Description |
---|---|
confirmParams (object) | Parameters that will be passed on to the Hyper API. |
redirect (string) | (web only) Can be either 'always' or 'if_required' By default, confirmWithCustomerDefaultPaymentMethod() will always redirect to your return_url after a successful confirmation. If you set redirect: "if_required", then this method will only redirect if your user chooses a redirection-based payment method. |
ConfirmParams object
confirmParams | Description |
---|---|
return_url(string) | (web only) The url your customer will be directed to after they complete payment. |