Using the Paysafe Request SDK
This section describes how to use the Paysafe Request SDK with ApplePay.
The basic steps are as follows:
- Include the Paysafe Request SDK in your HTML payment form.
- Add <div id="x-paysafe-apple-pay-button"></div> or similar to your payment form. The SDK needs a div element with an ID to be able to replace it with the Apple Pay payment button. The showButtons function refers to this div through its buttonOptions.selector parameter.
- Call the Request init function with your single-use token API key. This function initializes the Paysafe Request instance, validates the Paysafe Request options, and makes a request to the back-end to get merchant payment information matching the API key.
- Specify the onTokenization callback function, which receives the Paysafe single-use payment token generated by the Customer Vault API. onTokenization is called when the payment sheet is authorized by the user (using fingerprint or face ID). If no errors are returned the token is sent to the merchant, who will use it to complete the purchase.
- Call the showButtons function to display the Payment button for the specified paymentMethod. Clicking the payment button creates an Apple Pay session, during which the merchant is validated with Apple, and if everything is OK the payment sheet is displayed ready to take payment.
Optionally, you can do the following before calling showButtons:
- Call the canMakePayment function to verify that the customer's device is able to use Apple Pay before attempting to take payment. A callback returns this information, which you can then use to decide what to do next in your payment flow, such as display an error or show the payment buttons. The showButtons function also performs this verification, but if this fails, the payment will also fail.
- Update the options specified in the init function by calling the updateOptions function. You might want to do this because, for example, init has already been called with an amount, but your customer decides to select another item; by calling updateOptions you can update the amount.
All these functions may return errors, which are described here.
How Apple Pay interacts with the Paysafe Card Payments API to process the payment is described here.
Including the SDK
There are two ways to include the SDK:
- Include the latest official version - Paysafe strongly recommends this approach.
- Include a specific version.
Include the Latest Official Version
To include the latest official version of the SDK, use the following:
<head>
<script src="https://hosted.paysafe.com/request/v1/latest/paysafe.request.min.js"></script>
</head>
Paysafe recommends this approach as you will automatically receive all the latest updates and bug fixes.
Include a Specific Version
Each specific version of SDK is located at https://hosted.paysafe.com/request/version/paysafe.request.min.js. To include one of these, replace version with the version of the SDK you wish to use. For example:
<head>
<script src="https://hosted.paysafe.com/request/v2/paysafe.request.min.js"></script>
</head>
<head>
<script src="https://hosted.paysafe.com/request/v2/paysafe.request.min.js"></script>
</head>
Paysafe maintains compatibility between minor versions. For example, version 1.X.Y is compatible with version 1.V.W, but version 2.A.B would not be compatible with any version 1 release.
Apple Pay Minimal Example
The following code sample shows the Paysafe Request JavaScript for invoking only the essential elements: initializing the instance (init), defining how to return the payment token (onTokenization), and displaying the payment button that starts the Apple Pay session (showButtons).
<html>
<head>
<script type="text/javascript" src="https://hosted.paysafe.com/request/v1/latest/paysafe.request.min.js"></script>
</head>
<body>
...
<div id="x-paysafe-apple-pay-button"></div>
...
<script>
paysafe.request.init("my API key", {
country: "US",
currency: "USD",
amount: 1234,
label: "My label",
environment: "TEST"
});
paysafe.request.onTokenization(function (event, error) {
if (event) {
// Process the token - event.result.token
// Acknowledge - event.showSuccess() or reject event.showFailure()
event.showSuccess();
} else {
// handle error
}
});
paysafe.request.showButtons(function (displayedPaymentMethods, error) {
if (error) {
// handle error
}
});
</script>
</body>
</html>