Navigation¶

• Application Framework
  • API Overview
  • Making a REST API Call
  • API Authentication
  • WSDL Object Discovery
  • Framework Command APIs
    • Token Administration
    • Processing Payments
  • Response Codes
  • Tools and Resources
    

paymentkey.generate

Purpose of This Command¶

With PaymentKeys, you can encrypt a bank account or a credit card account and the "billing profile" information associated with that account into a single token that can be stored internally in your software and used in future payment transactions without the risk of exposing your customer's private information.
The paymentkey.generate command allows a merchant to generate a PaymentKey token for future use in live payment transactions.

A PaymentKey token may also be generated the first time a bank account or credit card account is used in a Payment transaction in the PaymentKeys Application Framework.
This command is useful if you prefer to generate a token outside of a payment transaction.

WSDL-Generated Objects Available For Use With This Command¶

• PK_Command
• PK_Response
  

Command Structure and Rules¶

The following table lists the required and optional fields for this command:

Field Name	Usage	Data To Be Sent
Command	Required	Set this field value to paymentkey.generate
Version	Required	Set this field value to 1.0
api_call_id	Required	A unique ID that your software assigns to the API call which ensures that this command is only processed once. More information can be found in the Authentication document of this WIKI.
TestMode	Optional	Set this value to On to test a command response without actually executing the command. Default value is Off.
PaymentAccountType	Required	Must be set to one of the following values to indicate the type of payment account being tokenized: echeck, visa, mastercard, discover, amex
Required Fields When Tokenizing an ECheck/ACH Bank Account
RoutingNumber	Required	The ABA routing number on customer’s check.
BankAccountNumber	Required	The customer’s bank account number .
BankAccountType	Required	Value must be Checking or Savings
CheckType	Required	Value must be Personal or Business.
Required Fields When Tokenizing a Credit Card Account
CardNumber	Required	The full 15 or 16 digit account number on the credit card
Expiration	Required	The expiration date on the credit card (format: MMYYYY).
Required/Optional Fields For All Payment Account Types
Billing_CustomerID	Optional	An internal identifier you have assigned to this customer.
Billing_FirstName	Required	First name of the bank account or credit card account holder
Billing_LastName	Required	Last name of the bank account or credit card account holder
Billing_Company	Required	Company name associate with the payment account. Required if the CheckType field above is set to Business
Billing_Address1	Required	Street address of the payment account holder.
Billing_Address2	Optional	Additional street address information.
Billing_City	Required	City of the payment account holder.
Billing_State	Required	2-Letter state abbreviate for the state of the account holder.
Billing_Zip	Required	Zip Code (format: ##### or #####-####)
Billing_Country	Optional	2-letter country code (ISO 3166). Default is US.

Sample JSON Command String¶

The following is an example of what the JSON string might look like for this command:

There are
code examples below that demonstrate how to easily convert the PK_Command object (stubbed by the WSDL for this web service) into a JSON string like this one.

Response Structure and Rules¶

The following table lists the fields that will be returned in a JSON string response to the paymentkey.generate command:

Field Name	Field Contents	Max Length	Additional Information
CommandStatus	Returns one of the following values: • Approved • Error	10	Indicates the success or failure of the command issued.
ResponseCode	A 3 digit code indicating command success or reason for command failure.	3	Please refer to the API Response document in this wiki for a list of possible code values, their descriptions, and what additional information may be available in the more_info field.
Description	A description of the api response code value	255
ErrorInformation	Additional information to help determine the source of an error.	50
PaymentKey	A unique token assigned to the bank account or credit card account provided AND the billing profile associated with that payment account.	10	Store this token in your system for making future tokenized payments. For reference, the first letter of the PaymentKey corresponds to the
Command_ReferenceID	A unique reference ID assigned to each api call.	30	This value is only needed as a reference during support calls or questions about specific api command attempts.

Sample JSON Response String¶

The following is an example of what the JSON string sent in response to this command might look like:


The code examples below will demonstrate how to easily convert this JSON response string into the PK_PaymentKeyAdmin_Response object stubbed by the WSDL for this web service.

Code Samples¶

Visual Basic .NET

Imports PaymentKeys.API_Tookit ’Define a command object for populating command parametersDim PK_Command As New PK_PaymentKeyAdmin_Command ’Build the command to send to the PaymentKeys Application Framework PK_Command.command = "paymentkey.generate" PK_Command.version = "1.0" PK_Command.api_call_id = Guid.NewGuid.ToString PK_Command.paymentkey = "v1111_00000_00000_00000.pk"’Serialize the command object to a JSON stringDim serializer As New System.Web.Script.Serialization.JavaScriptSerializer() Dim api_call As String = serializer.Serialize(PK_Command) ’Create HMACSHA1 signature hash for the JSON command string using the GatewayCodeDim sha1 As New System.Security.Cryptography.HMACSHA1() ’Specify the GatewayCode secret key sha1.Key = System.Text.Encoding.UTF8.GetBytes("PK_Demo") ’Convert the JSON command string to a byte arrayDim byteArray As Byte() = System.Text.Encoding.UTF8.GetBytes(api_call) ’Generate the hash signatureDim api_sig As String = Convert.ToBase64String(sha1.ComputeHash(byteArray)) ’Post HTTP Request data using the HTTPFormPost Utility from the PaymentKeys API ToolkitDim FormPost As New HTTPFormPost() FormPost.URL = "https://www.paymentkeys.com/api.rest/appserver" FormPost.Add_FormField("api_keyID", "PaymentKeys_Demo.pk") FormPost.Add_FormField("api_sig", api_sig) FormPost.Add_FormField("api_call", api_call) FormPost.Add_FormField("api_output", "json") Try FormPost.Submit() Catch ex As Exception: ’Handle HTTP communication exceptions hereEnd Try’Deserialize JSON response string into response objectIf Not (FormPost.ResponseText = String.Empty) Then Dim PK_Response As PK_PaymentKeyAdmin_Response: PK_Response = serializer.Deserialize(Of PK_PaymentKeyAdmin_Response)(FormPost.ResponseText) ’Parse the Response per your application and policy rules: Select Case PK_Response.status: Case""Success": ’Process successful response: Case "Declined": ’Process Decline response: Case "Error": ’Process Error response: End SelectEnd If

C# .NET

using PaymentKeys.API_Tookit; //Define a command object for populating command parameters PK_PaymentKeyAdmin_Command PK_Command = new PK_PaymentKeyAdmin_Command(); //Build the command to send to the PaymentKeys Application Framework PK_Command.command = "paymentkey.generate"; PK_Command.version = "1.0"; PK_Command.api_call_id = Guid.NewGuid.ToString; PK_Command.paymentkey = "v1111_00000_00000_00000.pk"; //Serialize the command object to a JSON string System.Web.Script.Serialization.JavaScriptSerializer serializer = new System.Web.Script.Serialization.JavaScriptSerializer(); string api_call = serializer.Serialize(PK_Command); //Create HMACSHA1 signature hash for the JSON command string using the GatewayCode System.Security.Cryptography.HMACSHA1 sha1 = new System.Security.Cryptography.HMACSHA1(); //Specify the GatewayCode secret key sha1.Key = System.Text.Encoding.UTF8.GetBytes("PK_Demo"); //Convert the JSON command string to a byte arraybyte[] byteArray = System.Text.Encoding.UTF8.GetBytes(api_call); //Generate the hash signaturestring api_sig = Convert.ToBase64String(sha1.ComputeHash(byteArray)); //Post HTTP Request data using the HTTPFormPost Utility from the PaymentKeys API Toolkit HTTPFormPost FormPost = new HTTPFormPost(); FormPost.URL = "https://www.paymentkeys.com/api.rest/appserver"; FormPost.Add_FormField("api_keyID", "PaymentKeys_Demo.pk"); FormPost.Add_FormField("api_sig", api_sig); FormPost.Add_FormField("api_call", api_call); FormPost.Add_FormField("api_output", "json"); try{ FormPost.Submit(); }catch (Exception ex) {: //Handle HTTP communication exceptions here}//Deserialize JSON response string into response objectif (!(FormPost.ResponseText == string.Empty)) { PK_PaymentKeyAdmin_Response PK_Response = default(PK_PaymentKeyAdmin_Response);: PK_Response = serializer.Deserialize<PK_PaymentKeyAdmin_Response>(FormPost.ResponseText); //Parse the Response per your application and policy rules: switch (PK_Response.status): {: case "Success":: //Process successful response: break;: case "Declined":: //Process Decline response: break;: case "Error":: //Process Error response: break;: }}