Authentication

A quickstart guide to authenticating with Number services

Basics

To authenticate to our services, depending on your integration of choice, you might need the following:

1

An account code and token

Using your unique key representing the Number account and the token generated from the Client Admin Portal, you'll be able to authenticate to both the REST and SOAP API.

2

API key

When initializing either of the mobile SDKs, you'll need an API key provided by Number.

3

HMAC secret

If you are PCI Compliant and want to use our REST API to collect cardholder data, some endpoints will require you to append additional data to the session header. You'll be able to generate this header using an HMAC secret provided by us.

If you have your own PCI compliant program and want to handle cardholder data using our REST API, you'll need to supplement the authentication header with the HMAC secret and you'll need to use our RSA certificate to encrypt cardholder data.

4

Username and password

When logging into the Virtual Terminal you'll need a username and password. When logging into the Client Admin Portal this will also require two-factor authentication using a text message to your mobile phone.

---

REST and SOAP API

Here's a basic step-by-step guide on how to authenticate with our APIs:

1

Find your account code

This will be provided by Number when you create an account with us.

2

Create a new token

Use the Client Admin Portal to create a token. If you don't have access to the Client Admin Portal, contact the Number support team.

3

Send a request to authenticate and store the session key

You'll need to provide your account code as AcctCode and token as Token.

REST API: POST /APIcardProcREST/v1.0.0/Authenticate SOAP API: Authenticate

Handle the response and store the SessKey value.

4

Include the session key in your requests

If you don't encounter a PCI Level 1 compliance warning in API reference page:

For REST API, include a SessKey header with the stored value. For SOAP API, include a SessKey parameter in the request body.

In case you encounter the compliance warning in API reference page, as seen below:

The methods below are for PCI Level 1 compliant merchants only. These operations involve sensitive credit card data. Additionally, they require a secured header. If you are not PCI compliant, use our PayForm widget instead.

You'll need to prepare a secured header and use its value in place of the original SessKey.

If the HMAC secret was not provided to you previously or you don't know how to find the value of UserID or DeviceID, contact Number.

The format for the key is as follows: ___. Include this key in the same way as you would include the SessKey (see case above).

C#

var sessKey = "9B9175EF556E4DDA93303132323141303035383339";
var hmacSecret = "7D55DBB3D691C9E0FDF341E4AB38C3C9";
var userId = 123;

var hash = string.Empty;
var epoch = (int)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds;
using (var hmac = new HMACSHA256(Encoding.ASCII.GetBytes(hmacSecret)))
{
  string hashable = string.Format("{0}_{1}_{2}", sessKey, epoch, userId);
  var bytes = hmac.ComputeHash(Encoding.ASCII.GetBytes(hashable));
  hash = BitConverter.ToString(bytes).Replace("-", "");
}

var signature = string.Format("{0}_{1}_{2}_{3}", 
  sessKey, epoch, userId, hash);

Java

String sessKey = "9B9175EF556E4DDA93303132323141303035383339";
String hmacSecret = "7D55DBB3D691C9E0FDF341E4AB38C3C9"; 
String userId = "123"; 

String hash;
String epoch = Long.toString(new Date().getTime() / 1000L); 
Try {
  Mac sha256HMAC = Mac.getInstance("HmacSHA256");
  SecretKeySpec secretKey = new SecretKeySpec(
    hmacSecret.getBytes(), "HmacSHA256");
  sha256HMAC.init(secretKey);
  String hashable = sessKey + "_" + epoch + "_" + userId;
  hash = Hex.encodeHexString(sha256HMAC.doFinal(hashable.getBytes()));
} catch (NoSuchAlgorithmException | InvalidKeyException e) {
  // handle signing exceptions
}
String signature = String.join("_", sessKey, epoch, userId, hash);

JavaScript (Postman)

// In the Pre-Request Script Tab in Postman:
var sessKey = '9B9175EF556E4DDA93303132323141303035383339';
var hmacSecret = '7D55DBB3D691C9E0FDF341E4AB38C3C9';
var userId = '123';

// hash sessKey, epoch, and userId with hmacSecret
var epoch = Math.floor(Date.now() / 1000);
var hash = CryptoJS.HmacSHA256(`${sessKey}_${epoch}_${userId}`, hmacSecret);
const signature = `${sessKey}_${epoch}_${userId}_${hash}`;

pm.collectionVariables.set("token", signature.toUpperCase());

// In the headers tab, create a new header with 
// the name SessKey and set the value to {{token}}

If you want to read more about authentication, see the Authentication guide

---

Android and iOS SDK

Authenticating with the mobile SDKs is very simple. Contact Number to get an API key, HMAC secret, and an optional Sentry DSN.

After installing the SDK of your choice, you can configure and initialize the EasyPay class.

GitHub - Easy-Pay-Solutions/Mobile-SDK-Android: Use Easy Pay Solution's credit card gateway within your Android appGitHub

Android SDK

GitHub - Easy-Pay-Solutions/Mobile-SDK-IOS: Use Easy Pay Solution's credit card gateway within your iOS appGitHub

iOS SDK

Android

Configure the EasyPay class at the very beginning of the application lifecycle, e.g. in the main Application class (in the onCreate() method).

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        EasyPay.init(applicationContext, "YOUR_API_KEY", "YOUR_HMAC_SECRET", "SENTRY_DSN")
    }
}

iOS

Configure EasyPay class. You can do that in your Payment Module or in AppDelegate (didFinishLaunchingWithOptions). Set isProduction = true to enable jailbroken device detection.

EasyPay.shared.configureSecrets(apiKey: "YOURAPIKEY",
                                hmacSecret: "YOURHMACSECRET",
                                sentryKey: "YOURSENTRYKEY", 
                                isProduction: Bool)

---

Virtual Terminal

To log in and use the features of Virtual Terminal, you'll first need to create accounts for your users through the Client Admin Portal.

To access the portal, Contact Number. You will be asked to provide the full name, e-mail address, and cell phone number for every individual you wish to have access to the portal. Those individuals will then be able to enter the portal and create new Virtual Terminal users through the portal by entering Manage Accounts > Users through the navigation on the left.

Now, those users will be able to access the Virtual Terminal using the link below.

https://easypay5.com/VTeasypay5.com

Virtual Terminal