Payment.Void Command

RSS

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 Name	Usage	Data To Be Sent
Command	Required	Set this field value to payment.void
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 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.
TestMode	Optional	Set this value to On to test a command response without actually executing the command. Default value is Off.
Command_ReferenceID	Required	The 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 Name	Field Contents	Max Length	Additional Information
CommandStatus	Returns one of the following values: Approved Declined 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 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.
Description	A description of the api ResponseCode 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.
Command_ReferenceID	A unique reference ID assigned to each API command request.	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:

{"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;: }}