REST API

Getting started with the REST API for Number

Our REST API allows full integration of Number services with a high degree of customization. You can use our REST API reference to learn about specific methods in the API.

Before you continue this section, we recommend reading sections about authentication, best practices, and input validation.

Examples

Authenticate

An example of using the Authenticate method.

private void Authenticate() {
  /// create request with account code and Token 
  string jsonContent = "{\"AcctCode\":\"EP9142446\",\"Token\":\"F31D16BA862F4EC6AE95CB90450C826A\"}";

  byte[] data = Encoding.UTF8.GetBytes(jsonContent);

  // Specify Number Endpoint 
  string MyUrl = "https://easypay5.com/APIcardProcREST/v1.0.0/Authenticate";

  // create a webrequest 
  WebRequest request = WebRequest.Create(MyUrl);
  request.Method = "POST";
  request.ContentType = "application/json";
  request.ContentLength = data.Length;
  string responseContent = null;


  ///  Important to handle any exceptions 
  try
  {
    // execute request 
    using (Stream stream = request.GetRequestStream())
    {
      stream.Write(data, 0, data.Length);
    }
    using (WebResponse response = request.GetResponse())
    {
      using (Stream stream = response.GetResponseStream())
      {
        using (StreamReader sr = new StreamReader(stream))
        {
          responseContent = sr.ReadToEnd();
        }
      }
    }
  }
  catch (Exception ee)
  {
    ///  consume any communication exceptions and abort
    MessageBox.Show("Communication Exception : " + ee.Message);
    /// important to insert your Logging function here
    return;

  }

  /// parse Json in any number of ways  , we use Newtonsoft 
  var AuthResp = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(responseContent);

  var MyResp = AuthResp.AuthenticateResult;

  ///  here are the important values to consume
  bool FunctionOk = (bool)MyResp.FunctionOk;
  bool AuthSuccess = (bool)MyResp.AuthSuccess;
  int ErrCode = (int)MyResp.ErrCode;
  string ErrMsg = (string)MyResp.ErrMsg;
  string RespMsg = (string)MyResp.RespMsg;

  //Check for unexpected Errors on cloud servers. If errors found log Error info and abort;
  if (!FunctionOk)
  {
    MessageBox.Show("Aspen Error : " + ErrMsg + " : ErrorCode: " + ErrCode);
    /// important to insert your Logging function here
    return;
  }

  //Check for failures such as Invalid or Expired Credentials or Inactive Account.
  if (!AuthSuccess)
  {
    MessageBox.Show("Failed Authentication : " + RespMsg);
    /// important to insert your Logging function here
    return;
  }

  /// Arriving here means that the Authentication was successful. You will retrieve a SessionKey and 
  /// a list of Merchant Records associated with this account. The session key will be used for all
  /// subsequent API calls within the next 25 hours 
  string SessKey = (string)MyResp.SessKey;
  var MerchantList = MyResp.MerchantList;
}

An example of using ConsentAnnual_ProcPayment method.

public static async Task<string> ProcessConsent( )
{
  string responseData = string.Empty;

  HttpClient httpClient = new HttpClient();

  /// Number Endpoint
  string apiUrl = "https://easypay5.com/APIcardProcREST/v1.0.0/ConsentAnnual/ProcPayment";
  
  // Here is your consentID and amount of purchase
  string jsonContent = "{\"ConsentID\": 1 ,\"ProcessAmount\": 52.00 }";

  HttpContent content = new StringContent( jsonContent, System.Text.Encoding.UTF8, "application/json");
  HttpResponseMessage response = new HttpResponseMessage();

  // add your session Key to Header
  httpClient.DefaultRequestHeaders.Add("SessKey", "8D85FD7E140A4098AB303330323241303430333238");

  try
  {
    response = await httpClient.PostAsync(apiUrl, content);
  }
  catch (Exception ee)
  {
    return "Exception : " + ee.Message;
  }

  if (response.IsSuccessStatusCode)
  {
    // Handle successful POST response
    responseData = await response.Content.ReadAsStringAsync();
  }
  else
  {
    // handle http error
    return "http error code " + response.StatusCode;
  }


  var saleResponse = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(responseData);

  var procPaymentResult = saleResponse.ConsentAnnual_ProcPaymentResult;

  // Here are some of the important values 
  bool FunctionOk = (bool)procPaymentResult.FunctionOk;
  bool TxApproved = (bool)procPaymentResult.TxApproved;
  int ErrCode = (int)procPaymentResult.ErrCode;
  string ErrMsg = (string)procPaymentResult.ErrMsg;
  string RespMsg = (string)procPaymentResult.RespMsg;

  int TxID = (int)procPaymentResult.TxID;
  string TxnCode = (string)procPaymentResult.TxnCode;



  //Check for Aspen Errors on cloud servers. If errors found log Error info and abort;
  if (!FunctionOk)
  {
    return "Aspen Error : " + ErrMsg + " : ErrorCode:" + ErrCode;
  }

  //check for card issuer decline 
  if (!TxApproved)
  {
    return "Declined Transaction : " + RespMsg + " : " + TxnCode;
  }


  return "Approved Transaction " + TxID.ToString() + " : Approval Code " + TxnCode;

}

Void Transaction

An example of using CardSale_Void method.

public static async Task TransactionVoid(string sessKey, int txID)
{
  using HttpClient httpClient = new HttpClient();
  string apiUrl = "https://easypay5.com/APIcardProcREST/v1.0.0/CardSale/Void";

  string jsonContent = $$"""
    {"TxID":{{txID}}}
  """;

  HttpContent content = new StringContent(
    jsonContent, System.Text.Encoding.UTF8, "application/json");
  httpClient.DefaultRequestHeaders.Add("SessKey", sessKey);
  HttpResponseMessage response = await httpClient
    .PostAsync(apiUrl, content);

  if (!response.IsSuccessStatusCode)
  {
    MessageBox.Show("Error code: " + response.StatusCode);
    // <Insert your Logging function here>
    return;
  }

  var voidResponse = Newtonsoft.Json.JsonConvert
    .DeserializeObject<dynamic>(
      await response.Content.ReadAsStringAsync());
  var voidResult = voidResponse.Transaction_VoidResult;

  // Here are some of the important values 
  bool functionOk = (bool)voidResult.FunctionOk;
  int errCode = (int)voidResult.ErrCode;
  string errMsg = (string)voidResult.ErrMsg;
  string respMsg = (string)voidResult.RespMsg;

  bool txApproved = (bool)voidResult.TxApproved;
  int resultTxId = (int)voidResult.TxID;

  // Check for unexpected error on server
  if (!functionOk)
  {
    MessageBox.Show(errMsg + " ErrorCode: " + errCode);
    // <Insert your Logging function here>
    return;
  }

  // Check for declined transaction
  if (!txApproved)
  {
    MessageBox.Show(respMsg + " Decline Code: " + txnCode);
    // <Insert your Logging function here>
    return;
  }
  else
  {
    MessageBox.Show(respMsg + " Approval Code: " + txnCode);
    // <Insert your Logging function here>
    // <Do something with the response if needed>
    return;
  }
}

Credit Transaction

An example of using CardSale_ApplyCredit method.

public static async Task TransactionCredit(
  string sessKey, int txID, decimal creditAmount)
{
  using HttpClient httpClient = new HttpClient();
  string apiUrl = "https://easypay5.com/APIcardProcREST/v1.0.0/CardSale/ApplyCredit";

  string jsonContent = $$"""
    {"TxID":{{txID}},"CreditAmount":{{creditAmount}}}
  """;

  HttpContent content = new StringContent(
    jsonContent, System.Text.Encoding.UTF8, "application/json");
  httpClient.DefaultRequestHeaders.Add("SessKey", sessKey);
  HttpResponseMessage response = await httpClient
    .PostAsync(apiUrl, content);

  if (!response.IsSuccessStatusCode)
  {
    MessageBox.Show("Error code: " + response.StatusCode);
    // <Insert your Logging function here>
    return;
  }

  var creditResponse = Newtonsoft.Json.JsonConvert
    .DeserializeObject<dynamic>(
      await response.Content.ReadAsStringAsync());
  var creditResult = creditResponse.Transaction_ApplyCreditResult;

  // Here are some of the important values 
  bool functionOk = (bool)creditResult.FunctionOk;
  int errCode = (int)creditResult.ErrCode;
  string errMsg = (string)creditResult.ErrMsg;
  string respMsg = (string)creditResult.RespMsg;

  bool txApproved = (bool)creditResult.TxApproved;
  int resultTxId = (int)creditResult.TxID;

  // Check for unexpected error on server
  if (!functionOk)
  {
    MessageBox.Show(errMsg + " ErrorCode: " + errCode);
    // <Insert your Logging function here>
    return;
  }

  // Check for declined transaction
  if (!txApproved)
  {
    MessageBox.Show(respMsg + " Decline Code: " + txnCode);
    // <Insert your Logging function here>
    return;
  }
  else
  {
    MessageBox.Show(respMsg + " Approval Code: " + txnCode);
    // <Insert your Logging function here>
    // <Do something with the response if needed>
    return;
  }
}

Query Transaction

An example of using Query_Transaction method.

public static async Task TransactionQuery(string sessKey, string query)
{
  using HttpClient httpClient = new HttpClient();
  string apiUrl = "https://easypay5.com/APIcardProcREST/v1.0.0/Query/Transaction";

  string jsonContent = $$"""
    {"Query":"{{query}}"}
  """;

  HttpContent content = new StringContent(
    jsonContent, System.Text.Encoding.UTF8, "application/json");
  httpClient.DefaultRequestHeaders.Add("SessKey", sessKey);
  HttpResponseMessage response = await httpClient
    .PostAsync(apiUrl, content);

  if (!response.IsSuccessStatusCode)
  {
    MessageBox.Show("Error code: " + response.StatusCode);
    // <Insert your Logging function here>
    return;
  }

  var queryResponse = Newtonsoft.Json.JsonConvert
    .DeserializeObject<dynamic>(
      await response.Content.ReadAsStringAsync());
  var queryResult = queryResponse.Transaction_QueryResult;

  // Here are some of the important values 
  bool functionOk = (bool)queryResult.FunctionOk;
  int errCode = (int)queryResult.ErrCode;
  string errMsg = (string)queryResult.ErrMsg;
  string respMsg = (string)queryResult.RespMsg;

  // Check for unexpected error on server
  if (!functionOk)
  {
    MessageBox.Show(errMsg + " ErrorCode: " + errCode);
    // <Insert your Logging function here>
    return;
  }

  var transactions = queryResult.Transactions;
  
  // <Display your transactions here>
}

An example of using Query_ConsentGeneral method.

public static async Task ConsentGeneralQuery(string sessKey, string query)
{
  using HttpClient httpClient = new HttpClient();
  string apiUrl = "https://easypay5.com/APIcardProcREST/v1.0.0/Query/ConsentGeneral";

  string jsonContent = $$"""
    {"Query":"{{query}}"}
  """;

  HttpContent content = new StringContent(
    jsonContent, System.Text.Encoding.UTF8, "application/json");
  httpClient.DefaultRequestHeaders.Add("SessKey", sessKey);
  HttpResponseMessage response = await httpClient
    .PostAsync(apiUrl, content);

  if (!response.IsSuccessStatusCode)
  {
    MessageBox.Show("Error code: " + response.StatusCode);
    // <Insert your Logging function here>
    return;
  }

  var queryResponse = Newtonsoft.Json.JsonConvert
    .DeserializeObject<dynamic>(
      await response.Content.ReadAsStringAsync());
  var queryResult = queryResponse.ConsentGeneral_QueryResult;

  // Here are some of the important values 
  bool functionOk = (bool)queryResult.FunctionOk;
  int errCode = (int)queryResult.ErrCode;
  string errMsg = (string)queryResult.ErrMsg;
  string respMsg = (string)queryResult.RespMsg;

  // Check for unexpected error on server
  if (!functionOk)
  {
    MessageBox.Show(errMsg + " ErrorCode: " + errCode);
    // <Insert your Logging function here>
    return;
  }

  var consents = queryResult.Consents;

  // <Display your consents here>
}

Generate Receipt

An example of using ReceiptGenerate method.

public static async Task ShowReceipt(
  string sessKey, int refID, int receiptType, int recipient)
{
  /* ReceiptType 1 TRANSACTION RECEIPT
   * ReceiptType 2 VOID RECEIPT
   * ReceiptType 3 REFUND RECEIPT
   * ReceiptType 4 ANNUAL RECEIPT
   * ReceiptType 5 RECURRING RECEIPT
   * ReceiptType 6 SUBSCRIPTION RECEIPT
   
   * Recipient 1 MERCHANT COPY
   * Recipient 2 CUSTOMER COPY
   * Recipient 3 DUAL COPY */


  using HttpClient httpClient = new HttpClient();
  string apiUrl = "https://easypay5.com/APIcardProcREST/v1.0.0/Receipt/ReceiptGenerate";

  string jsonContent = $$"""
    {"REFID":{{refID}}, "ReceiptType":{{receiptType}}, "Recipient":{{recipient}}}
  """;

  HttpContent content = new StringContent(
    jsonContent, System.Text.Encoding.UTF8, "application/json");
  httpClient.DefaultRequestHeaders.Add("SessKey", sessKey);
  HttpResponseMessage response = await httpClient
    .PostAsync(apiUrl, content);

  if (!response.IsSuccessStatusCode)
  {
    MessageBox.Show("Error code: " + response.StatusCode);
    // <Insert your Logging function here>
    return;
  }

  var receiptResponse = Newtonsoft.Json.JsonConvert
    .DeserializeObject<dynamic>(
      await response.Content.ReadAsStringAsync());
  var receiptResult = receiptResponse.ReceiptGenerateResult;

  // Here are some of the important values 
  bool functionOk = (bool)receiptResult.FunctionOk;
  int errCode = (int)receiptResult.ErrCode;
  string errMsg = (string)receiptResult.ErrMsg;
  string respMsg = (string)receiptResult.RespMsg;

  // Check for unexpected error on server
  if (!functionOk)
  {
    MessageBox.Show(errMsg + " ErrorCode: " + errCode);
    // <Insert your Logging function here>
    return;
  }

  /* Receipt generation successful. 
   * You may now add the HTML to your page.
   * <Logic to display HTML, e.g. 
   *  webBrowser1.DocumentText = response.ReceiptHtml;> */
}

Last updated

Was this helpful?