Safepay Atoms Overview

Install Safepay Atoms

Safepay Atoms provides a Web Component and a React Component (depending on the frontend framework your web application uses) to manage the Device Data Collection and Challenge flow for your customers.

To install our Atoms library using npm, run the following command from the root of your web application

Terminal

# Install the API librarynpm install @sfpy/atoms

If you're not using a package manager like npm, you can directly include the library in your HTML file by adding the following script tag to your HTML file:

<script src="https://unpkg.com/@sfpy/atoms@latest/dist/index.js"></script>

From the response recieved in the previous step, you can extract the access_token and device_data_collection_url to pass into the PayerAuthentication atom, along with the other required properties needed.

Setup PayerAuthentication Atom in React

import { Suspense, useRef } from 'react';
import { PayerAuthentication } from '@sfpy/atoms';
// Import the styles in your JavaScript/TypeScript project
import '@sfpy/atoms/styles'

        function AuthenticationForm() {
          const authRef = useRef(null);

          const handleFailure = useCallback((error: any) => {
            // customer was not able to complete payer authentication
            // handle the error scenario
            console.error('Payer authentication failed:', error);
          }, [])

          const handleSuccess = useCallback((data: any) => {
            // customer completed payer authentication
            // handle the success scenario
            console.log('Payer authentication succeeded:', data);
          }, [])

          return (
            <Suspense fallback={<div>Loading authentication...</div>}>
              <PayerAuthentication
                environment="sandbox"
                tracker="your-tracker"
                authToken="your-client-auth-token"
                deviceDataCollectionJWT="your-device-jwt"
                deviceDataCollectionURL="https://your-collection-url"
                authorizationOptions={{
                  do_capture: true // perform sale
                  do_card_on_file: true // tokenize customers card
                }}
                imperativeRef={authRef}
                onPayerAuthenticationFailure={handleFailure}
                onPayerAuthenticationSuccess={handleSuccess}
                onPayerAuthenticationFrictionless={handleSuccess}
                onPayerAuthenticationUnavailable={handleFailure}
                onSafepayError={handleFailure}
              />
            </Suspense>
          );
        }

Completing Payer Authentication

Based on whether your customer was able to successfully complete the challenge or not, the PayerAuthentication Atom will invoke the appropriate callback.

If there were any errors:

Show your customer the error message passed in the arguments
Close the modal
Direct your customer to try again using a different payment method or card

If payer authentication was successful:

Close the modal
Fetch the tracker using the Reporter API to verify the status
Redirect your customer to the order confirmation page

Depending on the options you passed into the PayerAuthentication atom, the tracker will either be in state TRACKER_AUTHORIZED or TRACKER_ENDED. You can optionally verify the status of the tracker using the Reporter API.

Fetch a tracker to get the status in NodeJS

const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', {
authType: 'secret',
host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com
});

        try {
          const response = safepay.reporter.payments.fetch(trackerToken)
        } catch (err) {
          console.log(error);
        }