Both the REST and SOAP APIs provide 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.
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 you obtain and use the same key until you receive one of above errors.
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:
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""
}}
}}";
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.
When you authenticate, you will receive FunctionOK and AuthSuccess flags in the response. You should handle the response as follows:
Check the FunctionOK flag.
If false, read the ErrMsg and ErrCode, and abort.
If true, read the AuthSuccess flag.
If AuthSuccess is false, read RspMsg and abort.
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.
SessKey string
A unique session key used for authentication in API calls. This key is generated upon successful authentication and must be included in all subsequent requests.
The AccountCode is a unique key which represents a Number account. This code will never change throughout the life of your account. Each AccountCode is 2 letters and 7 numbers. You can also use this code when communicating with Number support team.
Example:EP911XXXX
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.
// 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}}
Token string
The Token is a 32-characater hexadecimal string generated from the Client Admin Portal which acts as a password when authenticating to our APIs. A newly generated Token will be good for 2 years. Keep your tokens stored safely and securely, and do not email them without extra layers of security.
Example:2148B239CF6846BDA5D141BF4A4CFBE8
SessKey string
A unique session key used for authentication in API calls with requests that directly pass the cardholder data. To create this key, use the value generated upon successful authentication, a 16-byte HMAC secret, a RSA certificate, and must be included in subsequent requests.
