Submit a Transaction — Using a New Payment Method

Transactions entered with payment information must be submitted through a 3-step redirect process. This process protects the sensitive cardholder data that is involved. We call this payment information, and it includes the credit card number, expiration date, CVV code and cardholder name. The 3-step process avoids the payment information being posted to your server. Instead, it is posted directly to our server from your customer’s browser. Here’s an overview of how it works:

  • Step 1 : You submit the transaction details (less the payment information) to our transaction/start api. This returns a unique and one-time use only Form Post URL to which payment information can be securely posted.
  • Step 2: You display a form to collect the payment information and set it to submit to the Form Post URL (rather than your own server).
  • Step 3: Once the form posts, the API will redirect the browser to a URL of your choosing (specified by you in step1) and append a Token ID parameter. You will then call our transaction/complete api and include the Token ID. This tells us to finish processing the transaction.

Below are the details for each of the three steps.

Step 1

Transactions entered with payment information (i.e., credit card number) must be submitted through a 3-step redirect process.

URL Method
api/transaction/start POST

Parameters

Include the following JSON object with the post to describe the transaction.

Not all fields are required. You can omit optional ones per the rules below. Depending on which fields you supply, the transaction will be classified as Level I, II or III, each of which has different fees and rates associated.

For Level II and III transactions, there are special rules to control if new or existing shipping addresses are to be used. See the choices in the table below for a synopsis.

Field Description Required For Level
I II III
{
ApiKey: "string", your api key here * * *
MID: "string", your merchant account number * * *
ReturnUrl: "string", address of your step 3 method - the API will redirect here after you post the form in step 2. If you are using the api from a desktop or server application without a browser, this field can be empty and Step 2 will return the token id instead of redirecting a browser. * * *
TransactionType: "string", "sale", "auth", or "credit" * * *
Amount: number, total amount of transaction (including tax & shipping) * * *
TaxAmount: number, * *
ShippingAmount: number, * *
CustomerPONumber: "string", * *
Description: "string",
Choose one of the following for Customer:
1) If you want to create a new Customer...
CustomerId: number, set to 0 (indicates a new customer is being entered) * *
Customer: { * *
Name: "string", Must be unique (no duplicate customer names) * *
Code: "string", Must be unique (no duplicate customer codes)
PrimaryContact: "string",
PhoneNumber: "string",
EmailAddress: "string",
},
or 2) If you want to reference an existing Customer…
CustomerID: number, set to id of an existing customer * *
SaveNewPaymentMethod: bool, true to save payment method for future use; false to not save it. * *
BillingAddress: { * *
Address1: "string",
Address2: "string",
Address1: "string",
City: "string",
State: "string",
Postal: "string", Zip code * *
Phone: "string",
},
Choose one of the following for Shipping Address:
1) If you want to create a new Shipping Address...
ShippingId: number, Set to 0 (indicates a new shipping address is being entered) *
SaveNewShippingAddress: bool, true to save shipping address for future use; false to not save it. *
ShippingAddress: { *
Tag: "string", Ship to recipient *
Address1: "string",
Address2: "string",
City: "string",
State: "string",
Postal: "string", Zip code *
Phone: "string",
},
or 2) If you want to reference an existing Shipping Address...
ShippingId: number, Set to Id of an existing shipping address *
LineItems: [ Array of 1 or more line items. *
{
ProductCode: "string", Your product code from your product catalog. *
Quantity: number, *
Price: number, If not specified, the default price from your product catalog will be used.
}
]
}

Return Values

This API returns the following in JSON format if the operation is successful.

Field Description
{
FormPostUrl The URL to which you will post the payment information
ID 0 (disregard this field)
Success null (disregard this field)
Message true (disregard this field)
}

Step 2

URL Method
the FormPostUrl obtained in Step 1 POST

Parameters

Post the following fields from your payment information form to the FormPostUrl:

Field Description Required
billing-cc-number Credit card number *
billing-cc-exp Month and year in the form MMYY *
billing-cvv CVV code — 3 or 4 digits *
billing-first-name Cardholder first name
billing-last-name Cardholder last name
billing-track-1 If you are integrating a magnetic strip card reader, you can post the raw track data to these fields
billing-track-2

Return Values

After posting, the browser will redirect to the ReturnUrl you specified as a parameter in Step 1. It will append the following to that URL as a parameter:

Field Description
token-id A code for you to submit during Step3 to confirm your identity so the transaction can be completed

Step 3

URL Method
api/transaction/complete POST

Parameters

Include the following JSON object with the post to complete the transaction.

Field Description
{
TokenID Return Value of Step 2
}

Return Values

This API returns the following in JSON format if the operation is successful.

Field Description
{
ID Transaction ID
AuthorizationCode Authorization code for "sale" and "auth" transaction types (null for "credit" types)
CustomerID ID of the Customer
CustomerName Name of the Customer
Account Name of the customer account
TransactionType Sale, Authorization, Credit
TransactionTime Date and Time
Level 1,2,3
TotalAmount Total transaction amount including shipping and tax
Description Transaction description
TransactionSource “Virtual Terminal”
Status “Not Settled”
CaptureAmount Amount captured only if the transaction had a previous Auth
PaymentMethodID ID of the payment method stored in the vault
CardholderFirstName
CardholderLastName
CardType Visa, Mastercard, Discover, Amex
CardLast4 Last 4 digits of the customer credit card number
CustomerPONumber Level II/III only. Customer PO Number
TaxAmount Level II/III only. Tax Amount
ShippingAmount Level II/III only. Customer PO Number
Billing
  • Level II/III only:
  • {
  • Address1
  • Address2
  • City
  • State
  • Postal
  • Phone
  • Tag
  • }
ShippingAddressID Level II/III only: ID of the shipping address
Shipping
  • Level II/III only:
  • {
  • Address1
  • Address2
  • City
  • State
  • Postal
  • Phone
  • Tag
  • }
LineItems[]
  • Level II/III only: List of line items
  • {
  • Id
  • ProductCode
  • CommodityCode
  • Description
  • Price
  • UnitOfMeasure
  • Quantity
  • }
Success true
Message “Transaction Complete”
}