Express Checkout integration guide

Start accepting payments on your website or app.

How it works

When the shopper goes to checkout on your website, you redirect them to a Hosted Checkout page. After they make the payment, the shopper gets redirected to your page, and you show the shopper the outcome of the payment session.

1. When the shopper goes to your checkout and clicks on the "Payment" button, make a request to create a payment tracker.
2. After you have created the tracker, make a request to create an authentication token.
3. Use one of our SDKs to create the Checkout URL or follow the steps below to create the URL manually.
4. Return the URL to your client website or redirect the shopper to it.
5. After the shopper pays and are redirected back to your store, poll an endpoint on your server until you receive confirmation from Safepay through a webhook that the payment has been completed.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Safepay guide to:

• Get an overview of the steps needed to accept live payments.
• Create your test account.

After you have created your test account:

• Get your API keys.
• Set up webhooks to know the payment outcome.

Integration steps

1. Install an API library on your server
2. Create a payment tracker and authentication token from your server.
3. Generate the Checkout URL
4. Redirect the shopper to the Checkout URL.
5. Handle redirects
6. Show the payment status to your shopper
7. Handle webhooks
8. Update your order management system
9. Test your integration and go live.

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.payments.session.setup({
    "merchant_api_key": "SAFEPAY_API_KEY",
    "user": "cust_a7cc6fc1-088d-4f35-9dac-2bab2cb234a1",
    "intent": "CYBERSOURCE",
    "mode": "payment",
    "entry_mode": "raw",
    "currency": "USD",
    "amount": 10000,
    "metadata": {
      "order_id": "1234567890"
    },
    "include_fees": false
  })
} catch (err) {
  console.log(error);
}

{
  "data": {
    "tracker": {
      "token": "track_4f7d7e2d-ee05-44e3-81b7-6f6f2cca9727",
      "client": "sec_a8e0a889-b987-4b7e-9757-a6bf28e4d4e2",
      "environment": "sandbox",
      "state": "TRACKER_STARTED",
      "intent": "CYBERSOURCE",
      "mode": "payment",
      "entry_mode": "raw",
      "next_actions": {
        "CYBERSOURCE": {
          "kind": "PAYER_AUTH_SETUP"
        }
      },
      "purchase_totals": {
        "quote_amount": {
          "currency": "USD",
          "amount": 10000
        },
        "base_amount": {
          "currency": "PKR",
          "amount": 27800
        },
        "conversion_rate": {
          "base_currency": "PKR",
          "quote_currency": "USD",
          "rate": 278
        }
      }
    },
    "capabilities": {
      "CYBERSOURCE": true
    }
  },
  "status": {
    "errors": [],
    "message": "success"
  }
}

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.auth.passport.create()
} catch (err) {
  console.log(error);
}

{
  "data": "xnTyRgITVcHlyeKT2cf59_e836PouieQ6xPpuQiwFXD8M6HoJ283EP_zta2SKkm6B_IFNGEBmg=="
}

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 checkoutURL = safepay.checkouts.payment.create({
    // this the tracker.token from the payment session response
    tracker: "TRACKER_TOKEN",
    // the authentication token
    tbt: "AUTHENTICATION_TOKEN",
    // either production or sandbox
    environment: "sandbox",
    // attach a source, like your website domain or mobile app bundle identifier (or "mobile" for mobile webview)
    source: "mywebsite.com",
    // the success URL to redirect your customer to after payment complete
    redirect_url: "https://mywebsite.com/order/success",
    // the cancel URL to redirect your customer to after the customer cancels the checkout session
    cancel_url: "https://mywebsite.com/order/cancel"
  })
} catch (err) {
  console.log(error);
}

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

{
  "data": {
    "tracker": {
      "token": "track_1a46dc70-91f9-4892-8e25-0bb5205b69c7",
      "client": "sec_edeade52-46aa-483b-b87d-009d3ce41554",
      "environment": "sandbox",
      "state": "TRACKER_ENDED",
      "intent": "CYBERSOURCE",
      "mode": "payment",
      "next_actions": {
        "CYBERSOURCE": {
          "kind": "NOOP",
          "request_id": "req_9ea53be5-828f-4730-b187-9d3d350ab72a"
        }
      },
      "purchase_totals": {
        "quote_amount": {
          "currency": "PKR",
          "amount": 600000
        },
        "base_amount": {
          "currency": "PKR",
          "amount": 600000
        },
        "conversion_rate": {
          "base_currency": "PKR",
          "quote_currency": "PKR",
          "rate": 1
        }
      }
    },
    "action": {
      "token": "req_9ea53be5-828f-4730-b187-9d3d350ab72a",
      "payment_method": {
        "token": "card_353d4bd9-1d72-4f4d-a358-b277833795a4",
        "expiration_month": "12",
        "expiration_year": "2023",
        "card_type_code": "001",
        "card_type": "Visa",
        "bin_number": "445653",
        "last_four": "1096"
      }
    }
  },
  "status": {
    "errors": [],
    "message": "success"
  }
}

Mobile

For mobile, you may render the checkout session in a WebView. Note that when generating the checkout URL using the backend SDKs, you will need to set the source as mobile.

To mimic redirection, you can observe changes to the checkout URL and close the Webview on success or cancellation. The paths to observe are as follows:

Payment errors and retries

If the payment encounters an error, the shopper can retry the payment on the Hosted Checkout page. You receive a webhook for each payment attempt. So, you can receive more than one webhook with the same tracker.

For reference on what the payment.failed event contains, see the Webhook structure and types guide.

Expiration

The Hosted Checkout page expires after the authentication token expires. A single authentication token lasts for 1 hour. In case the authentication token expires, we prompt the shopper to return back to your store and restart the checkout process.

Test and go live

Before going live, use our list of test cards to test your integration. We recommend testing each payment method that you intend to offer to your shoppers. The test cards we have provided allow you test the following important scenarios:

• Frictionless authentication (both successful and unsuccessful)
• Step Up authentication (both successful and unsuccessful)
• Time outs

You can check the test payments in your Dashboard, under the Payments > Payments 2.0 tab.

When you are ready to go live, you need to:

1. Apply for a live account.
2. Submit a request to add payment methods on your live account.
3. Switch from test to our live endpoints.