PaymentKeys

Application Framework API
Endpoint https://www.paymentkeys.com/api.rest/appserver

Getting Started

Application Framework

What the platform provides and where it fits.

The PaymentKeys Application Framework
The PaymentKeys™ Application Framework (PKAF) allows software developers to easily extend their business software applications to include the full range of payment encryption, authentication, security, compliance and data management technologies developed and made available by PaymentKeys™, Inc.

The application framework services include:
  • PaymentKey Token Administration (creation, activation, updating, etc.)
  • Realtime and Batch Payment Processing
  • Recurring Payment Administration
  • Data Uploading and Management
    • Customer and Account Holder Profiles
    • Statements and Billing Data
    • Offline Payment Activity
  • PaySite (Custom Payment Website) Configuration and Administration
  • Reporting and Ad-Hoc Querying
The API documenation contained in this wiki will help you understand the foundational concepts of sending API commands to the PaymentKeys Application Framework gateway and the assoicated responses. Access to certain elements of this wiki may be restricted based on the IP address of the registered framework participant.

API Overview

Technology stack and design principles behind the gateway.

Overview

The PaymentKeys Application Framework takes advantage of several recent advancements in web service standards and technologies that are gaining wide-spread adoption because they result in web API's that are easier for programmers to implement and debug, provide better security, and result in lower message overhead and faster data communications on high-volume transaction systems. Traditional standards in web service technologies are also supported and utilized where they make sense to improve the overall easy-of-use and funcationality of the API.

These technologies include:
  • REST - A simpler, lighter approach to making API requests via HTTP
  • JSON - A light-weight data-interchange format
  • HMACSHA1 - A cryptographic hash technology that provides both sender and message authentication
  • XML - An established data-interchange protocol
  • WSDL - An established web services tool utilized in this API for stubbing client object (class) structures.
Although this list of acronyms and the associated linked documents may look daunting, these technologies are actually very simple to understand and implement. The rest of this wiki will give clear guidance for the template, structure and methods of making an API call to the PaymentKeys Application Framework servers utilizing these technologies.

Sample code is provided within the specific documentation for every API command to simplify the adoption of the PaymentKeys Application Framework into your software application.

Making a REST API Call

Single-endpoint request structure and templates.

Utilizing a REST-Based Approach to Web Services Technology

The PaymentKeys Application Framework API has been designed to take advantage of many of the best principles and recent advancements in web service technologies - including a REST-based approach to web services.

At its core, REST is simply a return to the basic principles of hyperlinking and using some of the basic methods of the HTTP protocol like POST and GET that made the world wide web so popular for retrieving data and exchanging information with web resources.

Please note that we use the term 'REST-based' instead of claiming a pure REST approach to our API methodology.

Although there is much debate about what makes for proper REST implementation, the PaymentKeys Application Framework focuses on the core principles of REST that make it so attractive as an alternative to the SOAP protocol for web services.

Specifically, a REST-based approach provides more widely established, compatible standards for exchanging data, a lighter data footprint, and broader flexibility and control over underlying data elements and rules.

The PaymentKeys REST Application Server Endpoint

The following URL is the secure endpoint to which all REST-based API calls to the PaymentKeys Application Framework servers will be made:
https://www.paymentkeys.com/api.rest/appserver

The Template for a Standard REST API Request

REST-based API calls are sent to the PaymentKeys REST Server as standard HTTP POST or GET requests.

Either method you choose for sending the API request will be accepted.
Data Fields Required In Each REST API Request
Your application needs to provide the following fields in every REST API request:
>
Field NameUsageData To Be Sent
api_keyIDRequired
The unique PaymentKey registered by your organization during sign-up.
api_sigRequiredThis field will contain a base64 encoded HMACSHA1 hash signature of the JSON string value in the api_call field.
Please see the Authentication
document of this wiki for more details and code examples.
api_callRequiredA JSON string containing the API command to execute and its associated command parameters
Using a REST approach, your application will send these fields and their URL-encoded values as traditional name/value pairs in an HTTP POST or GET request.
As you may have noticed, the actual API command and its parameters will be contained in the "api_call" field as a JSON string.
The other fields listed provide the PaymentKeys Application Framework server with the data necessary to identify the sender of the API call, authenticate the sender and the integrity of API call and to specify the format in which the response should be sent.

The reasons and advantages for separating the API command elements into a JSON string will become very clear as we move forward.
The Basic Structure of a JSON API Call
The following is a sample JSON string value for the api_call field that demonstrates the basic structure of an API command to the PaymentKeys Application Framework:
{"command":"paymentkey.activate","version": "1.0","api_call_id": "1AC4F-99B543-7FC0E","some_parameter1": "some_value1"}
The data elements of this string are adhere to the following structure:
>
Field NameUsageData To Be Sent
commandRequiredThe specific framework API command to execute
versionRequiredThe version of the command to execute as defined in the API documenation.
api_call_idRequiredA unique id assigned to the API call that allows the PaymentKeys servers to ensure that this specific command is only sent once and can never be sent again.
More about how this works and why its necessary can be found under the Authentication document of this WIKI.
ConditionalOptional or required fields to be included as a parameter for the API command (method) being executed.
If you are not familiar with how to read and understand JSON structures, please refer to http://www.json.org for more information.
The Reasons and Benefits of Using JSON For API Calls
Although we could have simply allowed each of these fields in an API call to be defined as tradtional HTTP POST or GET fields in the primary REST API request, there are several reasons why JSON was chosen as the data format for delivering the specific API command and parameters to be executed:
1. Object Serialization and Deserialization
A JSON string is simply a string that represents the structure and values of a complex runtime object.
Most popular programming languages provide tools or libraries to serialize a complex object directly into a JSON string and to deserialize a JSON string back into a complex object.

In contrast, constructing an HTTP POST or GET request usually requires the programmer to concatenate strings of name/value pairs together for each separate HTTP request.
The ability to easily serialize and deserialize a variety of different objects using JSON means that the PaymentKeys Application Framework can greatly simplify the programmer's development and interaction with the framework by providing pre-constructed classes through a traditional web service WSDL file for stubbing classes (objects).
These objects can then be used to simplify the contruction of api calls and the handling of the API responses.
2. JSON Strings Are Much Easier For Message Hashing
Most REST-based API's available on the web today require developers to take the name/value pairs of the typical REST API request and concatenate them in alphabetical order by field name in order to generate a hash signature that is based on consistent data for both parties.
Using a JSON string removes this unnecessary level of complexity and work for API developers.

You simply serialize your WSDL stubbed object containing your API command data into a JSON string (or concatenate the JSON string yourself - your choice), hash the JSON string as it is, assign the JSON string to your api_call variable of your HTTP POST or GET request and the PaymentKeys Application Framework has the exact string you serialized for authenticating your hash signature.

Putting It All Together - A Sample REST-Based API Request

Based on the rules and structures defined in this REST-based template, a command sent through the PaymentKeys Application Framework API using an standard HTTP GET request would look something like this (minus the whitespace, line breaks and lack of URL encoding for readability):
https://www.paymentkeys.com/api.rest/appserver?api_keyID=SomeCompany.pk
&api_sig=BuVwMhtnGPUh3u7wU/NGBnZ0hus=
&api_call={"command":"paymentkey.activate",
"version":"1.0",
"api_call_id":"1AC4F-99B543-7FC0E",
"some_parameter1":"some_value1"}
&api_output=json

API Authentication

HMAC-SHA1 shared-secret flow and avoiding replay.

Overview

The PaymentKeys Application Framework takes advantage a cryptographic hash technology called HMACSHA1 that provides both sender and message authentication. This hash method requires the use of a secret key for generating a one-way hash of the message being encrypted.

To provide authentication of a sender and the message being sent, the sender and receiver of the message use a shared secret key. The sender uses the secret key to generate the HMACSHA1 hash signature of the message to be sent. Then, the sender sends both the unencrypted message and the hashed signature of the message to the receiver.

The receiver uses the shared secret key to generate their own HMACSHA1 hash signature of the message. If the receiver's hash signature matches the sender's hash signature, then the receiver can be certain the message was sent by the receiver and that the message has not been tampered with in transit.

When the message is sent using SSL, SSL handles the responsibility of encrypting the overall HTTP string and any sensitive data it may contain.

The Shared Secret Key

Upon successful registration with PaymentKeys, your company was assigned and delivered a unique GatewayCode. This GatewayCode is the secret key that must be used when generating the HMACSHA1 hash signature for each API request sent to the PaymentKeys Application Framework gateway.

Generating the Hash Signature

As mentioned in the wiki document, Making a REST API Call, your software application will generated a JSON string that contains the API command to be executed and its associated parameters. This JSON string is the 'message' that you will hash using HMACSHA1 to generate the signature.

When you contruct your HTTP POST or GET request, the api_sig field needs to contain the base64 encoded hash signature you just generated and the api_call field will contain the unencrypted JSON string that defines the API command to execute.

Preventing Duplicate Message Authentication

The one problem with using a hash signature to authenticate a sender and their message is the fact that a message and its hash signature could be resent later by an unauthorized party and, without some additional security measures in place, the message would still authenticate.

To prevent this scenario from occurring, you will notice in the Framework Command APIs sections that every command sent as a JSON string includes a required field named api_call_id. The api_call_id field must contain a value that is unique and different for each api call. This field value allows the PaymentKeys servers to ensure that each specific API command is only sent once and can never be sent again.

Suggestions for the value of api_call_id include a GUID, a unique transaction ID generated internally by your software for each API call or even a string representation of the current date/time of your server down to the millisecond.

HMACSHA1 Code Samples and References

JAVA by SUN
Visual Basic .NET Framework 3.5 Example
’Define a command object for populating command parameters
Dim PK_Command As New PK_PaymentKeyAdmin_Command

’Build the command  to send to the PaymentKeys Application Framework
PK_Command.command = "paymentkey.activate"
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
Dim 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 GatewayCode
Dim 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 array
Dim byteArray As Byte() = System.Text.Encoding.UTF8.GetBytes(api_call)

’Generate the hash signature
Dim api_sig As String = Convert.ToBase64String(sha1.ComputeHash(byteArray))
C# .NET Framework 3.5 Example
//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.activate";
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 array
byte[] byteArray = System.Text.Encoding.UTF8.GetBytes(api_call);

//Generate the hash signature
string api_sig = Convert.ToBase64String(sha1.ComputeHash(byteArray));

WSDL Object Discovery

Use the WSDL to generate PK_Command and PK_Response objects.

URL for PaymentKeys Application Framework WSDL

About WSDL Object Stubbing AND REST

One of the best features of traditional SOAP XML web services is the ability to create class objects through WSDL discovery. These object can then be used during application design and runtime to exchange message information with a web service provider.

Unfortunately, one of the limitations with current REST-ful web service architecture and standards is a lack of tools and support for something resembling WSDL. Many REST-ful web service implementations rely on programmers writing code to concatenate strings of name/value pairs in order to transfer data between applications. This is a step backward for programmers - not a step forward.

The PaymentKeys Application Framework addresses this limitation by utilizing a popular technology called JSON for sending API calls and receiving API responses.

JSON was designed to represent the structure and values of complex runtime objects as a light-weight strings. JSON has the added benefit of enjoying wide-range support and most popular programming languages now provide tools or libraries to serialize a complex objects directly into JSON and deserialize JSON strings back into complex
objects.

By utilizing this ability to easily serialize and deserialize complex objects using JSON for the exchange of data, the PaymentKeys Application Framework can still provide pre-constructed class objects through a traditional WSDL discovery to greatly simplify the programmer's development and interaction with this REST-based API. The code examples throughout this documentation demonstrate how this works.

Token Administration

Overview

Generate and manage PaymentKey tokens.

Overview
The PaymentKey Application Framework gives merchants the ability to encrypt and decrypt bank or credit card account and billing profile data as PaymentKey Tokens and to manage their PaymentKey Tokens using the REST-based API commands listed on this page.
PaymentKey Token Administration Commands
paymentkey.generate
Encrypts bank or credit card account and billing profile data into a single PaymentKey token.
paymentkey.decrypt
Decrypts the bank or credit card account and billing profile data associated with a PaymentKey token.
paymentkey.deactivate
Deactivates and prohibits a PaymentKey token being used in any future payment transactions .

paymentkey.generate

Tokenize bank accounts or card data outside a payment call.

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 NameUsageData To Be Sent
CommandRequiredSet this field value to paymentkey.generate
VersionRequiredSet this field value to 1.0
api_call_idRequiredA 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.
TestModeOptionalSet this value to On to test a command response without actually executing the command. Default value is Off.
PaymentAccountTypeRequiredMust 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
RoutingNumberRequiredThe ABA routing number on customer’s check.
BankAccountNumberRequiredThe customer’s bank account number .
BankAccountTypeRequiredValue must be Checking or Savings
CheckTypeRequiredValue must be Personal or Business.
Required Fields When Tokenizing a Credit Card Account
CardNumberRequiredThe full 15 or 16 digit account number on the credit card
ExpirationRequiredThe expiration date on the credit card
(format: MMYYYY).
Required/Optional Fields For All Payment Account Types
Billing_CustomerIDOptionalAn internal identifier you have assigned to this customer.
Billing_FirstNameRequiredFirst name of the bank account or credit card account holder
Billing_LastNameRequiredLast name of the bank account or credit card account holder
Billing_CompanyRequiredCompany name associate with the payment account. Required if the CheckType field above is set to Business
Billing_Address1RequiredStreet address of the payment account holder.
Billing_Address2OptionalAdditional street address information.
Billing_CityRequiredCity of the payment account holder.
Billing_StateRequired2-Letter state abbreviate for the state of the account holder.
Billing_ZipRequiredZip Code (format: ##### or #####-####)
Billing_CountryOptional2-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:
{"Command":"paymentkey.generate",
"Version":"1.0",
"api_call_id":"1AC4F-99B543-7FC0E",
"TestMode":"On",
"PaymentAccountType":"echeck",
"RoutingNumber":"123123123",
"BankAccountNumber":"123456789",
"BankAccountType":"Checking",
"CheckType":"Personal",
"Billing_CustomerID":"12345",
"Billing_FirstName":"Jane",
"Billing_LastName":"Doe",
"Billing_Company":"Company LLC",
"Billing_Address1":"123 Some Street",
"Billing_Address2":"",
"Billing_City":"Dallas",
"Billing_State":"TX",
"Billing_Zip":"75001",
"Billing_Country":"US"
}
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 NameField ContentsMax LengthAdditional Information
CommandStatusReturns one of the following values:

Approved
• Error
10Indicates the success or failure of the command issued.
ResponseCodeA 3 digit code indicating command success or reason for command failure.3Please 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.
DescriptionA description of the api response code value255
ErrorInformationAdditional information to help determine the source of an error.50
PaymentKeyA unique token assigned to the bank account or credit card account provided AND the billing profile associated with that payment account.10Store this token in your system for making future tokenized payments.
For reference, the first letter of the PaymentKey corresponds to the
Command_ReferenceIDA unique reference ID assigned to each api call.30This 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:
{"CommandStatus":"Success","ResponseCode":"000","Description":"Command Successful","ErrorInformation":null,"PaymentKey":"123456","Command_ReferenceID":"45451-25141-0a0a"}
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;: }}

Processing Payments

Overview

Realtime payment operations and inline verification.

Overview
Payments may be authorized, processed, updated and voided in real-time using the following payment commands.
Bank accounts can optionally be verified separately or inline during a payment command.
The response to any payment command will indicate success or failure of the requested process.
Payment Commands
payment.process
Attempts to process an ECheck/ACH, Credit Card or Tokenized payment in real-time through your processor and indicates whether the payment was approved or declined.
payment.update
Modifies a payment transaction if it has not yet been batched by your processor.
payment.void
Cancels (stops) a payment from processing if it has not yet been batched by your processor.
payment.statustracking
Track all status changes that occur on a given date.


payment.authorize
Attempts to obtain authorization for a payment but does not process the payment until apayment.capture command is issued.
payment.capture
Finalizes and processes an authorized payment.
payment.verifybankaccount
Performs basic algorithm verification on a routing number and account number of a bank acccount. May also perform additional verification ifyour processorhas you enrolled in a verification service.
payment.update
Modifies a payment transaction if it has not yet been batched by your processor.
payment.refund
Reverses a previous debit and refunds the same amount (or less if specified) to the same payment account used in the original referenced debit.
payment.void
Cancels (stops) a payment from processing if it has not yet been batched by your processor.

payment.process

Process payments with optional verification.

Purpose of This Command

The payment.process command processes payments from a credit card or bank account to the merchant or it can be used to send payments to a bank account from the merchant (refunds, vendor payments, sales commissions, etc).

You have the ability to provide a credit card account, a bank account or a PaymentKey token as the desired payment method for each payment.

A PaymentKey token is an encrypted value that represents a credit card account or a bank account.
A token provides security and convenience to merchants who do not wish to store the payment account information of their customers.

A PaymentKey token can be generated and returned the first time you process a customer's payment through this payment.process API command.
From that point forward, you can submit the PaymentKey token instead of their payment account information on all future payment transactions.
You may also generate a PaymentKey token without processing a payment by using the paymentkey.generate command in this API.

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 NameUsageData To Be Sent
CommandRequiredSet this field value to payment.process
VersionRequiredSet this field value to 1.0
api_call_idRequiredA unique ID that your software assigns to the API call which allows the PaymentKeys servers to ensure that this specific command is only sent once and can never be sent again.
More information about how this works and why it is necessary can be found in the Authentication document of this WIKI.
TestModeOptionalSet this value to On to test a command response without actually executing the command. Default value is Off.
PaymentAccountTypeRequiredMust be set to one of the following values to indicate the type of payment account being tokenized: echeck, visa, mastercard, discover, amex, paymentkey
DateScheduledOptionalDate to process payment (format: mm/dd/yyyy).
AmountRequiredThe amount of the payment being processed.
Merchant_ReferenceIDOptionalAn internal ID or invoice number the merchant wants assigned to this payment
DescriptionOptionalA custom description for this payment
SendEmailToCustomerRequiredValue must be either Yes or No
Billing_EmailConditionalPayment notification email address. Required if SendEmailToCustomer is set to Yes.
Billing_PhoneOptionalThe phone number of the payment account holder
Customer_IPAddressConditionalThe customer’s IP Address if payment is made online.
Required if the SECCode field is set to WEB.
Generate_PaymentKeyOptionalValue must be either Yes or No.
Default value is set to No.
Required Fields When PaymentAccountType is paymentkey
PaymentKeyRequiredA PaymentKey token previously generated through the PaymentKeys Application Framework API that represents a customer's encrypted payment account and billing profile information.
Required Fields When PaymentAccountType is echeck
PaymentDirectionRequiredValue must be FromCustomer or ToCustomer
RoutingNumberRequiredThe ABA routing number on customer’s check.
BankAccountNumberRequiredThe customer’s bank account number .
BankAccountTypeRequiredValue must be Checking or Savings
CheckTypeRequiredValue must be Personal or Business.
CheckNumberOptionalThe check number on the customer's check.
SECCodeRequiredValue must be PPD, CCD, WEB, or TEL.
Required Fields When PaymentAccountType is visa, mastercard, discover, or amex
CardNumberRequiredThe full 15 or 16 digit account number on the credit card
ExpirationRequiredThe expiration date on the credit card
(format: MMYYYY).
The following fields are not required if the PaymentAccountType is paymentkey.
The PaymentKey token already contains the billing profile information.
However, you may use these fields to override the encrypted values in the token.
These fields are required for all other payment methods.
Billing_CustomerIDOptionalAn internal identifier you have assigned to this customer.
Billing_FirstNameRequiredFirst name of the bank account or credit card account holder
Billing_LastNameRequiredLast name of the bank account or credit card account holder
Billing_CompanyRequiredCompany name associate with the payment account. Required if the CheckType field above is set to Business
Billing_Address1RequiredStreet address of the payment account holder.
Billing_Address2OptionalAdditional street address information.
Billing_CityRequiredCity of the payment account holder.
Billing_StateRequired2-Letter state abbreviate for the state of the account holder.
Billing_ZipRequiredZip Code (format: ##### or #####-####)
Billing_CountryOptional2-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:
{
  "Command":"payment.process",
  "Version":"1.0",
  "api_call_id":"1AC4F-98B543-7FC0E",
  "TestMode":"On",
  "PaymentAccountType":"echeck",
  "Amount":"100.00",
  "Merchant_ReferenceID":"123456",
  "Description":"Invoice Payment",
  "SendEmailToCustomer":"Yes",
  "Billing_Email":test@paymentkeys.com,
  "Billing_Phone":"123-456-7890",
  "Customer_IPAddress":"123.123.123.123",
  "Generate_PaymentKey":"Yes",
  "PaymentDirection":"FromCustomer",
  "RoutingNumber":"123123123",
  "BankAccountNumber":"123456789",
  "BankAccountType":"Checking",
  "CheckType":"Personal",
  "CheckNumber":"1234",
  "SECCode":"CCD",
  "Billing_CustomerID":"12345",
  "Billing_FirstName":"Jane",
  "Billing_LastName":"Doe",
  "Billing_Company":"Company LLC",
  "Billing_Address1":"123 Some Street",
  "Billing_Address2":"",
  "Billing_City":"Dallas",
  "Billing_State":"TX",
  "Billing_Zip":"75001",
  "Billing_Country":"US"
}

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 NameField ContentsMax LengthAdditional Information
CommandStatusReturns one of the following values:
  • Approved
  • Declined
  • Error
10Indicates the success or failure of the command issued.
ResponseCodeA 3-digit code indicating command success or reason for command failure.3Please refer to the document titled Response Codes in this wiki for a list of possible code values, their descriptions, and what
additional information may be
available in the ErrorInformation field.
DescriptionA description of the api ResponseCode value255
ErrorInformationAdditional information to help determine the source of an error.50
PaymentKeyA unique token assigned to the bank account or credit card account provided AND the billing profile associated with that payment account.10Store this token in your system for making future tokenized payments.
Command_ReferenceIDA unique reference ID assigned to each API command request.30This 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:
{"CommandStatus":"Success","ResponseCode":"000","Description":"Command Successful","ErrorInformation":null,"PaymentKey":"e1111_d4cc5_a9b95_39405","Command_ReferenceID":"45451-25141-0a0a"}

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.
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;: }}

payment.update

Modify payment details after creation.

Purpose of This Command

The payment.update command updates the payment details of a Credit Card or ECheck/ACH payment ONLY if the payment status is still "Scheduled".

Any payment (Credit Card or ECheck/ACH) that is scheduled to occur on some future date will have a status of "Scheduled" and you can use this command to update any detail of the payment up until the date it is scheduled to process.

If you change the payment method from "paymentkey" to some other method, you will need to provide all of the the payment account and billing profile information as is detailed in the Payment.Process command.

Once a Credit Card payment is processed, it cannot be updated. If your processor has not yet batched out the credit card transactions for that day, you may instead be able to issue a Payment.Void command to void the Credit Card payment and process a new payment with the correct details.

An Echeck/ACH payment may remain in a "Scheduled" status at your processor until it is batched and sent to the Federal Reserve for processing. If this is the case, you may use the Payment.Update command to update any details of the ECheck/ACH payment, except one. You cannot change the payment from an ECheck/ACH payment to a Credit Card payment. In that is necessary, you would simply issue a Payment.Void command on the ECheck/ACH payment and use the Payment.Process command to create a new Credit Card payment

The Command_ReferenceID that was returned in response to the original payment will be required to reference the payment to update.

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 NameUsageData To Be Sent
CommandRequiredSet this field value to payment.update
VersionRequiredSet this field value to 1.0
api_call_idRequiredA unique ID that your software assigns to the API call which allows the PaymentKeys servers to ensure that this specific command is only sent once and can never be sent again.
More information about how this works and why it is necessary can be found in the Authentication document of this WIKI.
TestModeOptionalSet this value to On to test a command response without actually executing the command. Default value is Off.
Command_ReferenceIDRequiredThe unique Command_ReferenceID sent in response to the original Payment.Process command of the payment you wish to update.
PaymentAccountTypeOptionalMust be set to one of the following values to indicate the type of payment account being tokenized: echeck, visa, mastercard, discover, amex, paymentkey
DateScheduledOptionalDate to process payment (format: mm/dd/yyyy).
AmountOptionalThe amount of the payment being processed.
Merchant_ReferenceIDOptionalAn internal ID or invoice number the merchant wants assigned to this payment
DescriptionOptionalA custom description for this payment
SendEmailToCustomerOptionalValue must be either Yes or No
Billing_EmailConditionalPayment notification email address. Required if SendEmailToCustomer is set to Yes.
Billing_PhoneOptionalThe phone number of the payment account holder
Customer_IPAddressOptionalThe customer’s IP Address if payment is made online.
Required if the SECCode field is set to WEB.
Generate_PaymentKeyOptionalValue must be either Yes or No.
Default value is set to No.
Required Fields When PaymentAccountType is paymentkey
PaymentKeyOptionalA PaymentKey token previously generated through the PaymentKeys Application Framework API that represents a customer's encrypted payment account and billing profile information.
Required Fields When PaymentAccountType is echeck
PaymentDirectionOptionalValue must be FromCustomer or ToCustomer
RoutingNumberOptionalThe ABA routing number on customer’s check.
BankAccountNumberOptionalThe customer’s bank account number .
BankAccountTypeOptionalValue must be Checking or Savings
CheckTypeOptionalValue must be Personal or Business.
CheckNumberOptionalThe check number on the customer's check.
SECCodeOptionalValue must be PPD, CCD, WEB, or TEL.
Required Fields When PaymentAccountType is visa, mastercard, discover, or amex
CardNumberOptionalThe full 15 or 16 digit account number on the credit card
ExpirationOptionalThe expiration date on the credit card
(format: MMYYYY).
The following fields are not required if the PaymentAccountType is paymentkey.
The PaymentKey token already contains the billing profile information.
However, you may use these fields to override the encrypted values in the token.
These fields are required for all other payment methods.
Billing_CustomerIDOptionalAn internal identifier you have assigned to this customer.
Billing_FirstNameOptionalFirst name of the bank account or credit card account holder
Billing_LastNameOptionalLast name of the bank account or credit card account holder
Billing_CompanyConditionalCompany name associate with the payment account. Required if the CheckType field above is set to Business
Billing_Address1OptionalStreet address of the payment account holder.
Billing_Address2OptionalAdditional street address information.
Billing_CityOptionalCity of the payment account holder.
Billing_StateOptional2-Letter state abbreviate for the state of the account holder.
Billing_ZipOptionalZip Code (format: ##### or #####-####)
Billing_CountryOptional2-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:
{
  "Command":"payment.update",
  "Version":"1.0",
  "api_call_id":"0e07af5f-aef9-40a1-b250-d054bf3adb54",
  "TestMode":"On",
  "Command_ReferenceID":"45451-25141-0a0a",
  "Amount":"150.00",
}

Response Structure and Rules

The following table lists the fields that will be returned in a JSON string response to the paymentkey.update command:
Field NameField ContentsMax LengthAdditional Information
CommandStatusReturns one of the following values:
  • Approved
  • Declined
  • Error
10Indicates the success or failure of the command issued.
ResponseCodeA 3-digit code indicating command success or reason for command failure.3Please refer to the document titled Response Codes in this wiki for a list of possible code values, their descriptions, and what
additional information may be
available in the ErrorInformation field.
DescriptionA description of the api ResponseCode value255
ErrorInformationAdditional information to help determine the source of an error.50
PaymentKeyA unique token assigned to the bank account or credit card account provided AND the billing profile associated with that payment account.10Store this token in your system for making future tokenized payments.
Command_ReferenceIDA unique reference ID assigned to each API command request.30This 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:
{"CommandStatus":"Success","ResponseCode":"000","Description":"Command Successful","ErrorInformation":null,"PaymentKey":"e1111_d4cc5_a9b95_39405","Command_ReferenceID":"69714-35287-1b7c"}

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.
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;: }}

payment.void

Void a previously submitted payment.

Purpose of This Command

The payment.void command can be used to cancel any payment that has not yet been batched and submitted for processing by your processor.

A CommandStatus of "Declined" will be returned if it is no longer possible for your processor to void the payment.

The Command_ReferenceID that was returned in response to the original payment will be required to void that payment.

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 NameUsageData To Be Sent
CommandRequiredSet this field value to payment.void
VersionRequiredSet this field value to 1.0
api_call_idRequiredA unique ID that your software assigns to the API call which allows the PaymentKeys servers to ensure that this specific command is only sent once and can never be sent again.
More information about how this works and why it is necessary can be found in the Authentication document of this WIKI.
TestModeOptionalSet this value to On to test a command response without actually executing the command. Default value is Off.
Command_ReferenceIDRequiredThe unique Command_ReferenceID sent in response to the original Payment.Process command of the payment you wish to update.

Sample JSON Command String

The following is an example of what the JSON string might look like for this command:
{
  "Command":"payment.void",
  "Version":"1.0",
  "api_call_id":"0e07af5f-aef9-40a1-b250-d054bf3adb54",
  "TestMode":"On",
  "Command_ReferenceID":"45451-25141-0a0a"
}

Response Structure and Rules

The following table lists the fields that will be returned in a JSON string response to the paymentkey.void command:
Field NameField ContentsMax LengthAdditional Information
CommandStatusReturns one of the following values:
  • Approved
  • Declined
  • Error
10Indicates the success or failure of the command issued.
ResponseCodeA 3-digit code indicating command success or reason for command failure.3Please refer to the document titled Response Codes in this wiki for a list of possible code values, their descriptions, and what
additional information may be
available in the ErrorInformation field.
DescriptionA description of the api ResponseCode value255
ErrorInformationAdditional information to help determine the source of an error.50
PaymentKeyA unique token assigned to the bank account or credit card account provided AND the billing profile associated with that payment account.10Store this token in your system for making future tokenized payments.
Command_ReferenceIDA unique reference ID assigned to each API command request.30This 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:
{"CommandStatus":"Success","ResponseCode":"000","Description":"Command Successful","ErrorInformation":null,"PaymentKey":"e1111_d4cc5_a9b95_39405","Command_ReferenceID":"69714-35287-1b7c"}

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.
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;: }}

payment.statustracking

Track payment status throughout its lifecycle.

Purpose of This Command

The payment.statustracking command can be used to retrieve all payment status changes that occurred on a given day.

There are certain payments where the final funding status of a payment is not known at the time it is submitted. For example, the status of payments scheduled to occur on a future date and payments submitted by batch are not known when they are submitted and will not be known until that payment is processed. Also, due to the banking regulations for ACH payment, banks are to allowed return an ACH payment up to 3 business days after it is created or longer depending on the nature of the return. Payments may also be voided prior to settlement which would affect the funding status of that payment.

This command will allow you to query only for the status changes that occurred on a given day in response to these external events. You may choose to run this query multiple times per day to keep up with the latest status changes, but we suggest that you for sure run this query every day after 1:00 AM EST with the the tracking date set to the previous day to make sure that you have captured all status changes for that day.

Payment Events and Possible Resulting Status Values

The following table shows a list of external events that may occur on a payment over its lifetime and the possible status change that may result.
Possible EventsEvent NamePossible Status Values
Payment SubmittedSubmittedApproved, Declined, Error, Scheduled
Batched or Scheduled Payment ProcessedProcessedApproved, Declined, Error
Payment Voided By MerchantVoidedVoided
ACH Payment Returned By BankReturnedReturned
ACH Payment Returned After SettlementCharged BackCharged Back
Funds settlement of a payment does not change the status of a payment. All payments that receive an 'Approved' status are assumed to settle on each merchant's respective credit card and ACH settlement schedule unless the status of a payment is changed from 'Approved' to something else prior to the scheduled funding for that payment. Please talk to your account manager if you do not know the settlement schedule for your credit card or ACH payments.

WSDL-Generated Objects Available For Use With This Command

  • PK_Command

Command Structure and Rules

The following table lists the required and optional fields for this command:
Field NameUsageData To Be Sent
CommandRequiredSet this field value to payment.statustracking
VersionRequiredSet this field value to 1.0
api_call_idRequiredA unique ID that your software assigns to the API call which allows the PaymentKeys servers to ensure that this specific command is only sent once and can never be sent again.
More information about how this works and why it is necessary can be found in the Authentication document of this WIKI.
TrackingDateRequiredThe status event date for which you want to retrieve all status changes. You can use the ISO 8601 date format (yyyy-mm-dd) or the legacy date format (mm/dd/yyyy). If you are querying for the "today's" status events, you will only receive status updates known up until the moment of your query.

Sample JSON Command String

The following is an example of what the JSON string might look like for this command:
{
  "Command":"payment.statustracking",
  "Version":"1.0",
  "api_call_id":"0e07af5f-aef9-40a1-b250-d054bf3adb54",
  "TrackingDate":"09/01/2020"
}

Response Structure and Rules

The following table lists the fields that will be returned in a JSON string response to the paymentkey.statustracking command:
Field NameField ContentsMax LengthAdditional Information
CommandStatusReturns one of the following values:
  • Approved
  • Error
10Indicates the success or failure of the command issued.
ResponseCodeA 3-digit code indicating command success or reason for command failure.3Please refer to the document titled Response Codes in this wiki for a list of possible code values, their descriptions, and what
additional information may be
available in the ErrorInformation field.
DescriptionA description of the api ResponseCode value255
ErrorInformationAdditional information to help determine the source of an error.50
Command_ReferenceIDA unique reference ID assigned to each API command request.30This value is only needed as a reference during support calls or questions about specific api command attempts.
ResponseDataA JSON array of status change records for the given tracking date. Please refer to the Status Tracking Response Record Structure table in the next section of this document for details about the information in this JSON array.-The JSON array will be an empty array if there were no status events that occurred on the given Tracking Date.

Status Tracking Response Record Structure

The following table shows the structure and information that will be returned as a JSON array in the ResponseData field in response to the paymentkey.statustracking command:
Field NameData DescriptionMax Length
Command_ReferenceIDThe unique Command_ReferenceID sent in response to the original Payment.Process command.30
Merchant_ReferenceIDThe internal ID or invoice number the merchant assigned to this payment when it was submitted for processing.128
EventNameThe event that caused a status change for this payment. Please refer to the table in the section above titled Payment Events and Possible Resulting Status Values for a list of possible event names.20
Event_TimeStampThe date and time the event was recorded in the PaymentKeys system. All times are set to Central Standard Time.30
ResultingStatusThe status of this transaction resulting from the event that occurred. Please refer to the table in the section above titled Payment Events and Possible Resulting Status Values for a list of possible status values.20
ResponseCodePlease refer to the document titled Response Codes in this wiki for a list of possible code values, their descriptions, and what additional information may be available in the ErrorInformation field.30
DescriptionA description of the api ResponseCode value255
ErrorInformationThe date and time the event was recorded in the PaymentKeys system.128

Sample JSON Response String

The following is an example of what the JSON string sent in response to this command might look like:
{
"CommandStatus" : "Approved",
"ResponseCode" : "000"
"Description" : "Command Successful. Approved.",
"Command_ReferenceID" : "63735-89636-c42125",
"ResponseData" : [
{
"Command_ReferenceID" : "63735-73063-a0816d",
"EventName" : "Submitted",
"Event_TimeStamp" : "2020-09-14T13:08:23.7",
"ResultingStatus" : "Approved",
"ResponseCode" : "000",
"Description" : "Command Successful. Approved."
},
{
"Command_ReferenceID" : "63735-73236-7d5961",
"Merchant_ReferenceID" : "637357732367135565",
"EventName" : "Submitted",
"Event_TimeStamp" : "2020-09-15T13:10:16.753",
"ResultingStatus" : "Approved",
"ResponseCode" : "000",
"Description" : "Command Successful. Approved."
},
{
"Command_ReferenceID" : "63735-80867-801469",
"Merchant_ReferenceID" : "637357808669316275",
"EventName" : "Returned",
"Event_TimeStamp" : "2020-09-15T16:21:30.313",
"ResultingStatus" : "Returned",
"ResponseCode" : "R02",
"Description" : "Account Closed"
}
{
"Command_ReferenceID" : "63735-67830-ce9804",
"EventName" : "Charged Back",
"Event_TimeStamp" : "2020-09-15T12:21:31.217",
"ResultingStatus" : "Charged Back",
"ResponseCode" : "R10",
"Description" : "Customer Advises Not Authorized"
}
]
}
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.
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;: }}

Reference

Response Codes

All gateway, processor, and bank return codes.

Response CodeDescriptionContents of the ErrorInformation Field
API COMMAND SUCCESS
000Command Successful. Approved.
API COMMAND ERRORS
100Authentication Failed
101Invalid Command
102Duplicate Command Not Processedcall_id of the original command
103Transaction Cannot Be Modified
104Batch Cannot Be ModifiedBatch Status
105Invalid TransAct_ReferenceID
106Invalid BatchID
107Non-Unique Reference/Transaction IDField Name
108Invalid Reference/Transaction IDField Name
109Invalid Source IP
110Invalid Value In Message
INPUT DATA VALIDATION ERRORS
150Required Field MissingField Name
151Field Value Is Not ValidField Name
152Field Value Exceeds Maximum LengthField Name
PAYMENT ACCOUNT VERIFICATION FAILURES
200Failed AVS
201Failed CVN
202Failed Express Verify
203Invalid Credit Card Number
204No Such Card Issuer
205Expired Card
206Invalid Expiration Date
208Call Issuer for Further Information
209Invalid Routing Number
210Invalid Bank Account Number
211Invalid PIN
212Invalid PaymentKey
PAYMENT ACCOUNT DECLINES
300Transaction was Declined by Processor
301Transaction was Rejected by Gateway
302No Card Number on File with Issuer
304Invalid Account Type
305Account Closed
306Account Inactive
PAYMENT ACCOUNT DECLINES
307Account Frozen
309Insufficient Funds
310Over Limit
311Do Not Honor
312Transaction Not AllowedReason (if known)
313Invalid for DebitReason (if known)
314Invalid for CreditReason (if known)
315Customer Opt OutReason (if known)
316Customer Advises Not Authorized
317Manual Key Not Allowed
318Duplicate Transaction at Processor
319PaymentKey Authentication Failed
FRAUD DECLINES
400Pick Up Card
401Lost Card
402Stolen Card
403Fraudulent Card
404Excessive Declines From Same Source
405Excessive PIN Attempts
406Excessive Purchase Frequency
MERCHANT DIRECTIVES FROM PROCESSOR
500Declined - Stop All Recurring Payments
501Declined - Update Cardholder Data Available
502Declined - Further Instructions AvailableInstructions
503Declined - Call Processor for Voice Authorization
504Declined - Call Processor for Fraud Instructions
PROCESSOR ADMINISTRATIVE ERRORS
600Internal Gateway Error
601Internal Processor Error
602Communication Error with Issuer
603Communication Error with Processor
604Processor Feature Not Available
605Processor Format Error
606Invalid Terminal Number
607Merchant Not Setup
608Merchant Account is Inactive
609Invalid Merchant Configuration
610Invalid Payment Method for Merchant
611Unsupported Card Type
OTHER
999Contact Support Representative
ACH Return and Charge Back Codes
Response CodeDescription
NACHA RETURN CODES
R01Insufficient Funds
R02Account Closed
R03No Account, Unable to Locate Account
R04Invalid Account Number
R06Returned per ODFI's Request
R07Authorization Revoked by Customer
R08Payment Stopped
R09Uncollected Funds
R10Customer Advises not Authorized
R11Check Truncation Entry Return
R12Branch Sold to Another DFI
R13RDFI not qualified to participate
R14Representative Payee Deceased or Unable to Continue in that Capacity
R15Account Holder Deceased
R16Account Frozen
R17File Record Edit Criteria
R18Improper Effective Entry Date
R19Amount Field Error
R20Non-Transaction Account
R21Invalid Company Identification
R22Invalid Individual ID Number (CIE-MTE)
R23Credit Entry Refused by Receiver
R24Duplicate Entry
R25Addenda Error
R26Mandatory Field Error
R27Trace Number Error
R28Routing Number Check Digit Error
R29Corporate Customer Advises Not Authorized
R30RDFI Not Participant in Check Truncation Program
R31Permissible Return Entry (CCD and CTX only)
R32RDFI Non-Settlement
R33Return of XCK Entry
R34Limited Participation DFI
R35Return of Improper Debit Entry (CIE)
R36Return of Improper Credit Entry (RCK)
R37Source Document Presented for Payment
R38Stop Payment On Source Document
R39Improper Source Doc
R40Return of ENR Entry by Federal Government Agency (ENR only)
R41Invalid Transaction Code (ENR only)
R42Routing Number/Check Digit Error (ENR only)
R43Invalid DFI Account Number (ENR only)
R44Invalid Individual ID Number/Identification Number (ENR only)
R45Invalid Individual Name/Company Name (ENR only)
R46Invalid Representative Payee Indicator (ENR only)
R47Duplicate Enrollment (ENR only)
R50State Law Affecting RCK Acceptance
R51The Amount of the RCK Entry was not Accurately Obtained from the Item
R52Stop Payment on Item (adjustment entries)
R53Item and ACH Entry Presented for Payment
R61Misrouted Return
R62Incorrect Trace Number
R63Incorrect Dollar Amount
R64Incorrect Individual Identification
R65Incorrect Transaction Code
R66Incorrect Company Identification
R67Duplicate Return
R68Untimely Return
R69Multiple Errors
R70Permissible Return Entry Not Accepted
R71Misrouted Dishonored Return
R72Untimely Dishonored Return
R73Timely Original Return
R74Corrected Return
R80Cross-Border Payment Coding Error
R81Non-Participant in Cross-Border Program
R82Invalid Foreign Receiving DFI Identification
R83Foreign Receiving DFI Unable to Settle
R84Entry Not Processed by OGO
R89No Consumer Authorization
R90ABA does not pass MOD check
R91Invalid ABA. The nine (9) characters are not numeric
R92ABA not active
R93Not a valid Tran Code SEC combination
R94Amount must be zero (0) for pre-note
R95Amount must be greater then zero (0)
R96Not a valid Tran code
R97Not a valid SEC code
R98Encryption Error or Account number larger then 17 or empty set
R99OFAC possible match
VARIOUS PROCESSOR & BANK RETURN CODES
F41Rejected by Processor
I103DUPLICATE ITEM WITHIN FILE (BFA PROCESSING)
I104DUPLICATE ITEM IN DATABASE (BFA PROCESSING)
I106ITEM FILECODE DOES NOT BELONG TO BFA FILECODE (BFA PROCESSING)
I107ZERO OR NEGATIVE AMOUNT (BFA PROCESSING)
I108INVALID ROUTING NUMBER (BFA PROCESSING)
I109INVALID FORMAT FOR ACCT NUMBER (BFA PROCESSING)
I110INVALID FORMAT FOR CHECK NUMBER (BFA PROCESSING)
I111ITEM AMOUNT OVER HARD MAX LIMIT (BFA PROCESSING)
I112ACCOUNT ON BLOCKED ACCT LIST (BFA PROCESSING)
M1Routing Number Failed Check Digit Validation
M10Name is Invalid
M11Amount is Missing
M12Amount is Invalid
M13Account Type is Missing
M14Account Type is Invalid
M15Company Code is Invalid
M16Rejected by Processor
M17Rejected by Processor
M18Rejected by Processor
M19Rejected by Processor
M2Routing Number is Missing
M20SEC Code is Missing
M21Credit Transaction for WEB or TEL SEC Code
M22SEC Code is Invalid
M23FH_Template_ID is Missing or Invalid
M24Rejected by Processor
M25Rejected by Processor
M26Rejected by Processor
M27Rejected by Processor
M28Rejected by Processor
M29Rejected by Processor
M3Account Number is Missing
M30Rejected by Processor
M31Rejected by Processor
M32Rejected by Processor
M33Rejected by Processor
M34Rejected by Processor
M35Rejected by Processor
M36Rejected by Processor
M37Rejected by Processor
M38Rejected by Processor
M39Rejected by Processor
M4Rejected by Processor
M40Rejected by Processor
M41Rejected by Processor
M42Rejected by Processor
M43Rejected by Processor
M44Rejected by Processor
M45Rejected by Processor
M46Rejected by Processor
M47Rejected by Processor
M48Rejected by Processor
M49Rejected by Processor
M5Rejected by Processor
M50Rejected by Processor
M51Dollars Daily Max Threshold Exceeded
M52Dollars Monthly Max Threshold Exceeded
M53Transactions Daily Max Threshold Exceeded
M54Transactions Monthly Max Threshold Exceeded
M55Dollars Daily per Consumer Max Threshold Exceeded
M56Rejected by Processor
M57Rejected by Processor
M58Rejected by Processor
M59Rejected by Processor
M6Rejected by Processor
M60Rejected by Processor
M61Duplicate Entry
M62Rejected by Processor
M63Company is Suspended
M64Bank Account Blocked (ChargeBack)
M65Bank Account Blocked (NOC)
M66Company is Terminated
M67Credit Reserve Balance Exceeded
M68Rejected by Processor
M69OFAC
M7Rejected by Processor
M70Rejected by Processor
M71Rejected by Processor
M72Rejected by Processor
M73Rejected by Processor
M74Rejected by Processor
M75Merchant Requested Manual Cancel
M76Rejected by Processor
M77Rejected by Processor
M78Rejected by Processor
M79Rejected by Processor
M8Rejected by Processor
M80Rejected by Processor
M81Selected for Random Telephone Inquiry
M82Selected for Random Email Inquiry
M83Rejected by Processor
M84Rejected by Processor
M85Rejected by Processor
M86Rejected by Processor
M87Rejected by Processor
M88Rejected by Processor
M89Rejected by Processor
M9Name is Missing
M90MyECheck: address is invalid
M91MyECheck: RDFI is missing in RoutingNumbers table
M92Rejected by Processor
M93Rejected by Processor
M94Rejected by Processor
M95Declined on the Web
M96Consumer Requested Block
M97RDFI Stopped
M98Rejected by Processor
M99Unvalidated
NEWNew Account
P00ACCOUNT NOT LOCATED
P01ACCOUNT CLOSED
P02STOP PAYMENT
P03NO DEBITS
P04NO CHECKS
P05NSF
P06UNCOLLECTED FUNDS
P07NON DDA ACCOUNT
P50NON PARTICIPANT
P70VALIDATED
P71ATTACHED
S01Invalid Routing Number
S02Blocked Routing/Account Number
S03Failed to Collect Offset Funding From Merchant
S04SEC Code Not Approved for Use
S05Payment data is missing or incomplete
S06Account Block Requested by Merchant
S07Unauthorized SEC Code
S09Voided by Processor/ODFI
S10Invalid Account Number
S11Previously Returned R02, R03, R04 or R20
V02ACCOUNT NOT APPROVED
V10INVALID ROUTING NUMBER
V90PREAUTH VENDOR UNAVAILABLE
V91PREAUTH VENDOR ERROR

Tools & Resources

Direct links to the bundled .NET HTTP POST samples.

C# .NET HTTP POST Sample

Ready-to-use HttpWebRequest example in C#.

//Define a command object for populating command parameters
PK_PaymentKey_Activate_Command PK_Command = new PK_PaymentKey_Activate_Command();

//Build the command  to send to the PaymentKeys Application Framework
PK_Command.command = "paymentkey.activate";
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
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 array
byte[] byteArray = System.Text.Encoding.UTF8.GetBytes(api_call);

//   Generate the hash signature
string api_sig = Convert.ToBase64String(sha1.ComputeHash(byteArray));

//Submit the REST-based HTTP Request to the PaymentKeys Application Framework gateway
string PostURL = "https://www.paymentkeys.com/api.rest/appserver";
HttpWebRequest http_request = (HttpWebRequest)WebRequest.Create(PostURL);

//   Define the data to post
StringBuilder postData = new StringBuilder();
postData.Append("api_KeyID=PaymentKeys_Demo.pk");
postData.Append("&api_sig=" + Server.UrlEncode(api_sig));
postData.Append("&api_call=" + Server.UrlEncode(api_call));
postData.Append("&api_output=json");

//   Encode the post data into a byte array
System.Text.UTF8Encoding encodedData = new System.Text.UTF8Encoding();
byte[] postData_byteArray = encodedData.GetBytes(postData.ToString);

//   Set http request headers
http_request.Method = "POST";
http_request.ContentType = "application/x-www-form-urlencoded";
http_request.ContentLength = postData_byteArray.Length;

//   Stream the post data to the PaymentKeys application gateway
Stream request_stream = http_request.GetRequestStream();
request_stream.Write(postData_byteArray, 0, postData_byteArray.Length);
request_stream.Close();

//   Process the response
HttpWebResponse http_response = null;
StreamReader response_stream = null;
string JSON_Response = string.Empty;
try
{
    http_response = (HttpWebResponse)http_request.GetResponse();
    response_stream = new StreamReader(http_response.GetResponseStream(), Encoding.UTF8);
    JSON_Response = response_stream.ReadToEnd();
    }
    catch (WebException Ex)
    {

//Handle http communication errors here
    }
    finally
    {
    if ((http_response != null))
    {
    http_response.Close();
    http_response = null;
    }
    }

//Deserialize JSON response string into response object
if (!(JSON_Response == string.Empty))
{
    PK_PaymentKeyAdmin_Response PK_Response = default(PK_PaymentKeyAdmin_Response);
    PK_Response = serializer.Deserialize(JSON_Response);

//Parse the Response per your application and policy rules
switch (PK_Response.status)
    {
    case ...
}

VB.NET HTTP POST Sample

HttpWebRequest example in VB.NET.

		The following code demonstrates how to use HTTPWebRequest and HTTPWebResponse from the .NET Framework to perform an HTTP FORM POST:
Imports PaymentKeys.API_Tookit

’Define a command object for populating command parameters
Dim PK_Command As New PK_PaymentKeyAdmin_Command

’Build the command  to send to the PaymentKeys Application Framework
PK_Command.command = "paymentkey.activate"
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
Dim 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 GatewayCode
Dim 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 array
Dim byteArray As Byte() = System.Text.Encoding.UTF8.GetBytes(api_call)

’Generate the hash signature
Dim api_sig As String = Convert.ToBase64String(sha1.ComputeHash(byteArray))

'Initialize .Net web request variables
Dim PostURL As String = "https://www.paymentkeys.com/api.rest/appserver"
Dim http_request As HttpWebRequest = CType(WebRequest.Create(PostURL), HttpWebRequest)

'Define the data to post
Dim postData As New StringBuilder
postData.Append("api_KeyID=PaymentKeys_Demo.pk")
postData.Append("&api_sig=" & Server.UrlEncode(api_sig))
postData.Append("&api_call=" & Server.UrlEncode(api_call))
postData.Append("&api_output=json")

’Encode the post data into a byte array
Dim encodedData As New System.Text.UTF8Encoding
Dim postData_byteArray As Byte() = encodedData.GetBytes(postData.ToString)

’Set http request headers
http_request.Method = "POST"
http_request.ContentType = "application/x-www-form-urlencoded"
http_request.ContentLength = postData_byteArray.Length

’Stream the post data to the PaymentKeys application gateway
Dim request_stream As Stream = http_request.GetRequestStream()
request_stream.Write(postData_byteArray, 0, postData_byteArray.Length)
request_stream.Close()

’Process the response
Dim http_response As HttpWebResponse = Nothing
Dim response_stream As StreamReader = Nothing
Dim JSON_Response As String = String.Empty
Try
    http_response = CType(http_request.GetResponse(), HttpWebResponse)
    response_stream = New StreamReader(http_response.GetResponseStream(), Encoding.UTF8)
    JSON_Response = response_stream.ReadToEnd()
    Catch Ex As WebException

’Handle http communication errors here
Finally
If Not http_response Is Nothing Then
    http_response.Close()
    http_response = Nothing
    End If
End Try

’Deserialize JSON response string into response object
If Not JSON_Response = String.Empty Then
Dim PK_Response As PK_PaymentKey_Activate_Response
    PK_Response = serializer.Deserialize(Of PK_PaymentKey_Activate_Response)(JSON_Response)

’Parse the Response per your application and policy rules
Select Case PK_Response.status
    Case ...
End If
An unhandled error has occurred. Reload 🗙