Advanced Checkout integration guide

Install an API library

We provide two official server-side API libraries for Node and PHP that allow you to interact with the Safepay API easily. Our API libraries will save you time, because they:

• Use an API version that is up to date.
• Provide a simple interface to interact with the Safepay API.
• Handle common errors and exceptions.
• Send the request to Safepay using their built-in HTTP client, so you do not have to create your own.

Create a payment session

When your customer lands on your checkout page but before they click on the Pay button, you must create a Tracker with the relevant data. For example:

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

try {
  const response = safepay.payments.session.setup({
    "merchant_api_key": "YOUR_API_KEY",
    "user": "cust_a7cc6fc1-088d-4f35-9dac-2bab2cb234a1",
    "intent": "CYBERSOURCE",
    "mode": "payment",
    "entry_mode": "raw",
    "currency": "USD",
    "amount": 10000,
    "metadata": {
      "order_id": "1234567890"
    }
  })
} catch (err) {
  console.log(error);
}

It’s important to note that linking a Merchant Shopper to a tracker during the setup phase is advantageous as it prevents you from having to pass this information in later stages. To understand how to create and manage your Merchant Shoppers, please refer to our guide on merchant shoppers.

Generate a client token

After creating the payment session, the next step is to generate a temporary client token using the /client/passport/v1/token endpoint.

To do this, you first need to generate a temporary client-side authentication token. Make an API request from your server using one of our SDKs or your own custom solution.

For example:

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

try {
  const response = safepay.auth.passport.create()
} catch (err) {
  console.log(error);
}

The /client/passport/v1/token response will give you the authentication token you will need to authorize future requests to Safepay APIs from your website.

For example:

{
  "data": "xnTyRgITVcHlyeKT2cf59_e836PouieQ6xPpuQiwFXD8M6HoJ283EP_zta2SKkm6B_IFNGEBmg=="
}

Expiration

A single authentication token lasts for 1 hour. If the authentication token expires, any further requests to the Safepay APIs will result in a 401 Unauthorized error. You must regenerate the authentication token.

Payer Authentication

After creating the payment session and the client side token, the next step is to pass in the customer payment details to the Order API.

Important: If you pass in raw card details from your server, Safepay will require you to submit a PCI DSS Attestation of Compliance (AOC). If you don’t have a PCI DSS AOC, you must submit your customer’s card information directly from your website to our APIs. We strongly recommend you sending the customer’s card information through your client website.

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

try {
  const response = safepay.order.tracker.action({
    "payload": {
      "payment_method": {
        "card": {
          "card_number": "5200000000001096",
          "expiration_month": "12",
          "expiration_year": "2028",
          "cvv": "123"
        }
      }
    }
  })
} catch (err) {
  console.log(error);
}

The response for this action yields the card details along with the payer_authentication_setup object which carries the access_token and the device_data_collection_url. These are necessary for collecting the user's device data and passing the resulting fingerprint in the enrollment step.

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

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.

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.

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);
}

If you indicated that you also wanted to tokenize your customer’s payment credentials, the token will be available in the success callbacks as well as the customer’s wallet. You can verify this by fetching your customer’s wallet through the Fetch Customer Wallet API.