Navigation¶

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

Payment.Process Command

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 Name	Usage	Data To Be Sent
Command	Required	Set this field value to payment.process
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.
PaymentAccountType	Required	Must be set to one of the following values to indicate the type of payment account being tokenized: echeck, visa, mastercard, discover, amex, paymentkey
DateScheduled	Optional	Date to process payment (format:  mm/dd/yyyy).
Amount	Required	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	Required	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	Conditional	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	Required	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	Required	Value must be FromCustomer or ToCustomer
RoutingNumber	Required	The ABA routing number on customer’s check.
BankAccountNumber	Required	The customer’s bank account number .
BankAccountType	Required	Value must be Checking or Savings
CheckType	Required	Value must be Personal or Business.
CheckNumber	Optional	The check number on the customer's check.
SECCode	Required	Value must be PPD, CCD, WEB, or TEL.
Required Fields When PaymentAccountType is visa, mastercard, discover, or amex
CardNumber	Required	The full 15 or 16 digit account number on the credit card
Expiration	Required	The expiration date on the credit card (format: MMYYYY).
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	Required	First name of the bank account or credit card account holder
Billing_LastName	Required	Last name of the bank account or credit card account holder
Billing_Company	Required	Company name associate with the payment account. Required if the CheckType field above is set to Business
Billing_Address1	Required	Street address of the payment account holder.
Billing_Address2	Optional	Additional street address information.
Billing_City	Required	City of the payment account holder.
Billing_State	Required	2-Letter state abbreviate for the state of the account holder.
Billing_Zip	Required	Zip Code (format: ##### or #####-####)
Billing_Country	Optional	2-letter country code (ISO 3166). Default is US.

Sample JSON Command String¶

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

Response Structure and Rules¶

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

Field Name	Field Contents	Max Length	Additional Information
CommandStatus	Returns one of the following values: Approved 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: