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.

Please see the Payer Authentication Methods Available