Payment.Update Command

RSS

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 Name	Usage	Data To Be Sent
Command	Required	Set this field value to payment.update
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.
PaymentAccountType	Optional	Must be set to one of the following values to indicate the type of payment account being tokenized: echeck, visa, mastercard, discover, amex, paymentkey
DateScheduled	Optional	Date to process payment (format: mm/dd/yyyy).
Amount	Optional	The amount of the payment being processed.
Merchant_ReferenceID	Optional	An internal ID or invoice number the merchant wants assigned to this payment
Description	Optional	A custom description for this payment
SendEmailToCustomer	Optional	Value must be either Yes or No
Billing_Email	Conditional	Payment notification email address. Required if SendEmailToCustomer is set to Yes.
Billing_Phone	Optional	The phone number of the payment account holder
Customer_IPAddress	Optional	The customer’s IP Address if payment is made online. Required if the SECCode field is set to WEB.
Generate_PaymentKey	Optional	Value must be either Yes or No. Default value is set to No.
Required Fields When PaymentAccountType is paymentkey
PaymentKey	Optional	A 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
PaymentDirection	Optional	Value must be FromCustomer or ToCustomer
RoutingNumber	Optional	The ABA routing number on customer’s check.
BankAccountNumber	Optional	The customer’s bank account number .
BankAccountType	Optional	Value must be Checking or Savings
CheckType	Optional	Value must be Personal or Business.
CheckNumber	Optional	The check number on the customer's check.
SECCode	Optional	Value must be PPD, CCD, WEB, or TEL.
Required Fields When PaymentAccountType is visa, mastercard, discover, or amex
CardNumber	Optional	The full 15 or 16 digit account number on the credit card
Expiration	Optional	The 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_CustomerID	Optional	An internal identifier you have assigned to this customer.
Billing_FirstName	Optional	First name of the bank account or credit card account holder
Billing_LastName	Optional	Last name of the bank account or credit card account holder
Billing_Company	Conditional	Company name associate with the payment account. Required if the CheckType field above is set to *Business*
Billing_Address1	Optional	Street address of the payment account holder.
Billing_Address2	Optional	Additional street address information.
Billing_City	Optional	City of the payment account holder.
Billing_State	Optional	2-Letter state abbreviate for the state of the account holder.
Billing_Zip	Optional	Zip Code (format: ##### or #####-####)
Billing_Country	Optional	2-letter country code (ISO 3166). Default is US.

Sample JSON Command String¶

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

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