RSS

Navigation



Quick Search'''

Advanced Search »


Payment.StatusTracking Command

RSS

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









ScrewTurn Wiki version 5.2.0.8. Some of the icons created by FamFamFam.