Authentication

How to authenticate with the Number backend

The REST API provides their own methods for authenticating with Number. You will need to use them to receive a SessKey. To authenticate, you need to provide your AccountCode and Token.

---

---

---

As a result of authentication, you will obtain a session key. This key is required to prove your identity when using any of the other methods provided by our backend.

---

---

It is required that you manage a session key throughout any 24-hour period:

You will need to reauthenticate when one of the following two errors occurs:

Error 5030: Expired session - session key has expired after 25 hours

Error 5050: Unauthorized - your IP has changed since you last authenticated

The system will lock your IP out if you send 6 unsuccessful authentication attempts in a row. Always abort unsuccessful authentication attempts instead of retrying and notify the user. Only the Number support team can remove the lock from a merchant.

We recommend that either manage a session key object for 24 hours or simply use the key until you receive one of above errors at which time you will RE-Authenticate.

---

HMAC and RSA

The HMAC and RSA section only applies to using the REST API.

If you are not passing cardholder data through the REST API, you only need the session key to authenticate and connect to your account. Otherwise, you need to use a signature secured by an HMAC secret and and encrypt the cardholder data using our RSA certificate.

HMAC header

When required to secure the request, the SessKey header will need to include additional data.

---

---

This altered key should be passed instead of the plain session key using a header with the same name, SessKey. Here are some examples of creating the header signature:

RSA encryption

When the REST API traffic originates from unknown networks or mobile devices, we also mandate that any credit card numbers be encrypted prior to building your request. You can download our RSA 2048 certificate and use the public key to encrypt the cardholder information.

When passing cardholder data through our REST API, only the credit card number needs to be encrypted using RSA, the expiration date and CVV can be left as is.

When encrypting sensitive cardholder data, use RSA encryption padding of OaepSHA1. Encrypted card numbers will always have 512 bytes.

Examples of RSA encryption:

C#

using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;

// Example card number to encrypt
string myCardNumber = "4111111111111111";

X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
X509Certificate2? myCert = null;

store.Open(OpenFlags.ReadOnly);
bool certFound = false;

// Search for cert within store either by thumbprint or subject 
foreach (X509Certificate2 cert in store.Certificates)
{
  if (cert.Subject.Contains("mobile.easypay5.com"))
  {
    myCert = cert;
    certFound = true;
    break;
  }
}

if (!certFound || myCert == null)
{
  MessageBox.Show("Unable to find the certificate");
  return;
}

byte[] plainBytes = Encoding.UTF8.GetBytes(myCardNumber);
RSA? rsaPublicKey = myCert.GetRSAPublicKey();

if (rsaPublicKey == null)
{
  MessageBox.Show("Unable to get RSA public key from the certificate");
  return;
}

// Use the OaepSHA1 RSA encryption padding
byte[] encryptedBytes = rsaPublicKey.Encrypt(plainBytes,
  RSAEncryptionPadding.OaepSHA1);

// Convert to Base64 before sending to the API
string encryptedString = Convert.ToBase64String(encryptedBytes);

// Example payload for the API
string jsonPayload = $@"
{{
    ""ccCardInfo"": {{
        ""AccountNumber"": ""{encryptedString}"",
        ""ExpMonth"": 10,
        ""ExpYear"": 2028,
        ""CSV"": ""122""
    }}
}}";

Java

JavaScript (Node.js)

Encrypted test cards

Here are some test cards with encrypted card numbers for First Data Testing. Before you implement encryption, you can use them for testing in the Sandbox environment.

You can read more about testing in the Testing section.

Visa

Card number: 4761 5300 0111 1118

Encrypted string

K8ELXxBJGpgO02O9Rw3XYe32D4msyv2lBO/SaQyx2vkPjFdy8hBjOxKQ9Q9NMQro9HotSzdev0Legr+iwevfvMnZINZMAy7ufNA4CniT3YcNdOYbzATBD1iTTiLcf+/we9QHsuo70R7Mij9oONFdh5UX948v89ZQMc95RyXtXpU1sUXkf/GG+gm9XFG0y09pb7KCIwa8vxhbMej0I7k7xhR3t6651XWec7H4NVE6jqMOSK7S3/cuqU9eHhqOD24f3X8xnzrGQUTGEvfk63bsH4UgXq/lEo27yMSi0FpsBLyw7fE/1FsFQG58HgMoXmwdjGtHPSH4/xUXJHtihkKHi8Ge9Zch7k9v7ZiAAe48qUPmFs2bOH3XV3jtvPo3fX64vz3Ode37oehe06+MmQR7ho+cR/r/IDAA74zQWRgYfDL79UhaLEMCQ7mcoxGlRgz5gfOy1inD1mL14lPlH8FcTDcnlDBtwakzlSP8NrmtFGvz3gV9T3d9nAP2yBvP4qXF875rGhiXgQ8HQHAit0SyxMuqdNtnScUbTu4iUHqQr4xtsiOQ/MoJIFgygtPs4ndEpNAeImvr7+DgFQvhkZyDWJBQ8qqpv4vlO3pDAJ6/7UzSmSD5D9vjdFj9tAAf72cXLtu1STcB7XKzzrG696kBdYAWhoF/z72n1n4AtZGWMf0=

Mastercard

Discover

AMEX

---

Lockouts

When you authenticate, you will receive FunctionOK and AuthSuccess flags in the response. You should handle the response as follows:

1. Check the FunctionOK flag.

   1. If false, read the ErrMsg and ErrCode, and abort.

   2. If true, read the AuthSuccess flag.

      1. If AuthSuccess is false, read RspMsg and abort.

      2. If AuthSuccess is true, save the SessKey value.

Once again, it's important to abort unsuccessful authentication attempts and notify the user that new credentials need to be applied to the product.

The system will lock your IP after 6 unsuccessful attempts in a row. When a lockout occurs, our support department will need to manually audit it to determine if it's safe to remove the lock.

---

Token Renewal

The Client Admin Portal will allow you to create and manage all of your tokens. There is no limit to the number of tokens you can create. We recommend creating a separate token for each individual processing location (IP address).

Each token has a lifespan of 2 years since it was generated and will need to be replaced afterwards. This can only be done by physically logging into The Client Admin Portal. To make the process faster, The Client Admin Portal provides a way to POST new tokens to your web server to help automate a part of the renewal process.

To learn how to use the Client Admin Portal to renew tokens, see the Client Admin Portal guide.