@payfurl/client
v4.11.4
Published
Collect payment details in the browser and turn them into a payFURL payment token that your server charges through the [payFURL API](https://docs.payfurl.com/guides). Cards, PayPal, Google Pay, Apple Pay, PayTo, Click to Pay and more, through one integrat
Downloads
2,341
Readme
payFURL Client SDK
Collect payment details in the browser and turn them into a payFURL payment token that your server charges through the payFURL API. Cards, PayPal, Google Pay, Apple Pay, PayTo, Click to Pay and more, through one integration.
Card details are typed into fields that payFURL hosts in an iframe, so card numbers never reach your page's code.
Documentation · API reference · Changelog · Support
Install
npm install @payfurl/clientTo load the SDK from a <script> tag instead, see
Get started.
Quick start
Add a container inside your payment form:
<form method="POST" action="/pay">
<div id="payment"></div>
<button type="submit">Pay</button>
</form>Then add the Drop In UI, which shows every payment method your account has for the amount and currency:
import payfurl from "@payfurl/client";
payfurl
.init("sandbox", "<your public key>")
.addDropIn("payment", 20, "AUD");When the shopper submits the form, the SDK collects the payment details, adds the result to the form
as a hidden input, and submits it to your server: token for a card, transactionId for PayPal and
other payment types that complete the payment themselves. To keep the shopper on the page, handle the
result yourself:
payfurl
.onSuccess((message) => {
// message.token for a card, message.transactionId for PayPal and other payment types
// that complete the payment themselves
})
.onFailure((message) => console.error(message.error));Your public key is on Account Info in the payFURL dashboard. Use "production" and a production
key to go live.
Payment methods
| Method | Adds |
|---|---|
| addDropIn | Every payment method on your account, in one component |
| addCard | A card form |
| addPaypal | PayPal buttons |
| addGooglePay | A Google Pay button |
| addApplePay | An Apple Pay button |
| addPayTo | A PayTo agreement form |
| addCheckout | A third-party checkout, such as Afterpay or Affirm |
| addSavedPaymentMethods | A customer's saved cards |
Each has its own page in the documentation, with its options.
TypeScript
The package includes its type definitions. Every option type can be imported by name:
import payfurl, { type DropInOptionsType, type SuccessResponseType } from "@payfurl/client";
const options: DropInOptionsType = { allowedPaymentTypes: ["card", "googlepay"] };
payfurl.init("sandbox", "<your public key>")
.addDropIn("payment", 20, "AUD", options)
.onSuccess((message: SuccessResponseType) => console.log(message.token));React and Vue
@payfurl/react-plugin and
@payfurl/vue-plugin wrap the Drop In UI in a
component: see React and
Vue.
Changelog
What changed in each version of the payFURL Client SDK. The @payfurl/client npm package and the
script on assets.payfurl.com share version numbers, so this covers both. The changelog starts with
version 4.9.3.
4.11.4 (2026-11-18)
Added
- Apple Pay
buttonOptionsinaddApplePayand inaddDropIn'sapplePayOptions: set the Apple Pay button's style (black,whiteorwhite-outline), its type (such asdonate,check-out,subscribeorplain), its locale, and its width, height and corner radius. Without it, the button stays a black "Buy with Apple Pay" button in US English. The options don't apply to PayWay, which draws its own Apple Pay button.
4.11.3 (2026-11-17)
Changed
- The error reports the SDK sends to payFURL now include the page's address without its query string or fragment,
a random ID for the page visit, and the error's stack trace. Card details are still never included. Each error is
sent once per page, and an error thrown by your own
onSuccess,onFailure,onLoaded,onValidateoronValidationStatusChangehandler is no longer reported as an SDK error. Your handler's error still reaches the browser as before. - The SDK now also reports payment failures you could see but payFURL could not: API requests that fail with no response or a server error, the card form not loading, 3-D Secure failures, and Apple Pay, Google Pay or PayPal failing to load.
4.11.2 (2026-11-12)
Changed
- When the bank's 3-D Secure answer for a card is a failure, the card is still submitted to payFURL, so the failure
and its 3-D Secure result now show on the dashboard's Tokenise Failures page. The shopper sees the same message,
and
onFailuregets the sameerroranderrorDetails.reasonas before. isApplePayAvailable()is now documented to work beforeinit(), with no public key, as it already did: you can decide whether to offer Apple Pay before you set up the SDK. No upgrade is needed for this.
4.11.1 (2026-11-11)
Added
paypalButtonStyle, inaddPaypal()andaddDropIn(), also takes PayPal's button style as an object, such as{ color: 'black', shape: 'pill', label: 'pay' }, to set the buttons' shape, label, layout and height as well as their colour.addDropIn()takespaypalHideShipping, which redacts the shipping address from the PayPal site, ashideShippingdoes inaddPaypal().
Changed
- In TypeScript,
paypalButtonStyleis now typed as one of the colours (gold,blue,silver,white,black) or a button style object, in place of any string. If you pass a variable typedstring, type it asPaypalButtonColor, exported by@payfurl/client.
Fixed
addDropIn()now usespaypalButtonStyleandpaypalEnablePayIn4. Before, the drop-in always showed a gold PayPal button without Pay Later, whatever you passed.- When PayPal rejects the button style,
onPaymentMethodStatus()now reports PayPal asunavailable.
4.11.0 (2026-11-06)
Added
isApplePayAvailable()returns a promise of whether the shopper's browser can pay with Apple Pay: the same checkaddApplePay()andaddDropIn()use to decide whether to show the Apple Pay button.onPaymentMethodStatus()tells you when a Google Pay, Apple Pay, PayPal, PayTo, checkout (such as PayID or Zip) or UPI button or form has rendered, or that it won't and why: no provider for it on your account, not supported in the shopper's browser, or an error, such as a checkout that couldn't be created or invalid PayTo options. Before, these showed on the page only, or nowhere.onThreeDsProgress()tells you when 3-D Secure starts, when the shopper is shown a challenge, and when it completes, successfully or not.@payfurl/react-pluginand@payfurl/vue-plugin1.5.0:PayfurlDropintakesonPaymentMethodStatusandonThreeDsProgress(in Vue, the@onPaymentMethodStatusand@onThreeDsProgressevents), andcustomer,billingAddressandorderprops, which it could not receive before. Its Vue events are typed. They need this version of@payfurl/clientor later.- You can call
setCustomerInfo()afteraddCard()oraddDropIn(), for example when the shopper changes their email: the new email is used for 3-D Secure, and the card form hides its own Email field once it has a valid one. The same email now also reaches the fraud check and the card token.setCustomerInfo()is now the preferred way to pass the shopper's email;threeDSEmailstill works and is used whensetCustomerInfo()has no email.
Changed
- If your code reads
onFailure'serrortext to detect a 3-D Secure failure, readerrorDetails.reasoninstead. When 3-D Secure fails, the card form andonFailure'serrornow say "Your bank couldn't verify this card. Please try again or use a different card." in place of a technical message such as "3D Secure failed", which is now inerrorDetails.reason. - For PayPal,
onLoadedis now called once the PayPal buttons have rendered, rather than when they were requested, and not at all if they fail to render.
Fixed
- A shopper known to Click to Pay gets one passcode per checkout, not one each time your page calls
setCustomerInfo(). Click to Pay looks the shopper up again only when their email or phone changes to one not yet looked up, a second after the last change; a call without an email keeps the email it had. The passcode is sent only once the card form is on screen. Details set beforeaddCard()oraddCardLeastCost()start Click to Pay no longer start it early (preloadClickToPay()still loads it ahead). - The card form no longer grows to a large blank area while 3-D Secure runs: it keeps its height, with the loading spinner, until a challenge actually appears, and does not grow at all when the card passes without one.
- The card form's Email field, a PayTo PayID email and Click to Pay sign-in now accept email addresses
whose domain ends in more than three letters, such as
[email protected]. - PayTo now calls your failure handler when the agreement can't be created from what the shopper
entered ("Invalid payment details", with
errorDetailswhen available), and checkout providers and UPI when the payment fails after the shopper opened the provider's page ("Checkout has been cancelled"). Before, these errors only showed on the page. - In TypeScript,
providerIdandoptionsofaddApplePay()are now optional, as documented. - In the Drop In UI,
allowedPaymentTypes: ['payglocal']now shows PayGLocal. It used to need'zip', which also showed Zip. - Adding Google Pay or PayPal again after its script failed to load now loads it again.
- A checkout payment (such as PayID or Zip) no longer calls your success handler twice, or your failure handler after your success handler, when payFURL's status check answers slowly.
4.10.0 (2026-11-04)
Added
- TypeScript types. The package now includes type definitions for every method, option and handler,
so your editor suggests them and the TypeScript compiler checks your calls. Import the types by
name, for example
import payfurl, { type DropInOptionsType, type SuccessResponseType } from "@payfurl/client". setCurrency()changes the currency of the card, Google Pay, Apple Pay and saved payment method components already on the page, assetAmount()does for the amount. Add PayPal, PayTo and Checkout components again for a new currency.@payfurl/react-pluginand@payfurl/vue-plugin1.4.0 use these types for their props and events, and their own type definitions now load.
Fixed
- Google Pay errors now reach your failure handler. Closing the Google Pay sheet is still not a failure.
- The close button of the Ecentric 3-D Secure challenge now closes it.
@payfurl/react-plugin1.4.0:PayfurlDropinno longer fails when it mounts, and no longer rebuilds the drop-in, losing what the shopper typed, each time its parent re-renders. A newamountorsuccessMessageupdates the drop-in in place.
4.9.10 (2026-10-29)
Added
- Forter fraud screening for Google Pay and Apple Pay payments, on accounts that use Forter.
Fixed
- When you add several components at once, each now uses its own options and provider. A component added while another was still loading used to take the first one's.
- The loading spinner no longer reappears after a failed Forter 3-D Secure challenge.
4.9.9 (2026-10-25)
Fixed
- PayID through Azupay now appears in the Drop In UI. A Drop In with PayID as its only payment method never finished loading.
4.9.8 (2026-10-22)
Added
- Forter fraud screening for
tokeniseWith3Ds,tokeniseCard,addThreeDsWithTokenandaddSavedPaymentMethods, on accounts that use Forter. A payment that Forter declines stops when your account is set to stop declined payments.
Fixed
- PayPal payments on accounts that use Forter no longer fail at the fraud check.
- A card that skips 3-D Secure through network token authentication still gets the fraud check.
- A payment no longer waits forever when the fraud check or a Forter 3-D Secure result never answers: your failure handler is called instead.
4.9.7 (2026-10-21)
Fixed
- A Forter 3-D Secure challenge no longer fails when Forter's script loads after the challenge starts.
4.9.6 (2026-10-19)
Added
- Google Pay for CyberSource and NAB Gateway.
- The
billingDetailsRequiredGoogle Pay option, foraddGooglePayand the Drop In'sgooglePayOptions:trueasks the shopper for their email address and full billing address. CyberSource and NAB Gateway need it unless you pass the customer's name, email and billing address yourself.
4.9.5 (2026-10-13)
Changed
- Internal improvements. Nothing changes in how you use the SDK.
4.9.4 (2026-10-12)
Security
- 3-D Secure on a saved card token (
addThreeDsWithToken) no longer brings the card's details into the browser: it runs on the card your gateway stores.
Fixed
- Nuvei 3-D Secure stops after it reports a failure, instead of opening the challenge as well.
4.9.3 (2026-10-08)
Added
- The Apple Pay button now appears in Chrome, Firefox and Edge, where Apple lets shoppers pay with their iPhone. It used to appear in Safari only.
- Forter as a 3-D Secure provider on its own, without Forter fraud screening.
Fixed
- A Forter 3-D Secure challenge whose result is anything but a success now fails the payment.
- Forter's scripts use your account's Forter site ID.
