Hosted Payments API – Calls & Parameters

  1. Home
  2. Hosted Payments
  3. Hosted Payments API – Calls & Parameters

Hosted Payments

Print Friendly, PDF & Email

API – Calls and Parameters

Integration with Snap* Hosted Payments Web Services API is achieved through a HTTP-POST request from a merchant web site to the API. The API implements various ‘actions’ or functions, where an action includes one or more required action-specific API parameters in addition to the Common API request parameters. Upon completion of the requested action, the API returns a structured response array containing one or more parameters relevant to the specified action.

Note: Because requests to the API are designed to return a response result directly, a separate merchant callback is not generated for these API calls. Requests made to the Checkout API require JSON encoding on all parameters where the data type is not a string (e.g.: The sub_items[ ] array of request parameters.)

 

Customer Information should be included on all Orders, Subscriptions and Token requests. Any additional parameters allow you to assign return and cancel URLs, MAC, checkout layout, and create a token for additional payments.

 
CUSTOMER DETAIL
Required Name Value Format Notes
X customer[email] Customer email address Up to 50 chars Must be a valid email address
X customer[first_name] Customer first name Up to 32 chars
X customer[last_name] Customer last name Up to 32 chars
Optional customer[phone] Customer phone number Up to 15 chars
 
CUSTOMER CHECKOUT
Required Name Value Format Notes
Optional return_url URL to return the end user to after successful payment Up to 255 chars Defaults to the HTTP referrer
Optional cancel_url URL to return the end user to when they ‘Cancel’ payment Up to 255 chars Defaults to the HTTP referrer
X mac Message Authentication Code (MAC) 32 char hex See below
Optional auto_return True or False Boolean Defaults to false (show thank you page) Forced to true for iframe
Optional checkout_layout 'iframe' Up to 6 chars Omit to redirect browser
Optional create_token True or False Boolean Defaults to false (Order or Subscription checkouts only)

The EVO Snap* Hosted Payments service is designed for ease of use and to reduce PCI scope for one-time purchases. For a one-time purchase, the parameters listed MUST be passed as part of the HTTP-POST to the checkout interface.

 
ORDER DETAIL
Required Name Value Format Notes
X order[merchant_order_id] Merchant Order ID Up to 255 chars Must be unique
Optional order[billto_company] Customer 'bill to' company Up to 32 chars
Optional order[billto_first_name] Customer 'bill to' first name Up to 32 chars
Optional order[billto_last_name] Customer 'bill to' last name Up to 32 chars
X* order[billto_house_number] Customer 'bill to' house number Up to 32 chars *for international processing
Optional order[billto_address1] Customer 'bill to' address line 1 Up to 32 chars
Optional order[billto_address2] Customer 'bill to' address line 2 Up to 32 chars
Optional order[billto_city] Customer 'bill to' city Up to 32 chars
Optional order[billto_state] Customer 'bill to' state 2 chars Must be valid 2 char state code within country
Optional order[billto_country] Customer 'bill to' country 2 chars Must be valid 2 char ISO country code
Optional order[billto_zipcode] Customer 'bill to' ZIP/postal code Up to 10 chars
Optional order[shipto_company] Customer 'ship to' company Up to 32 chars
Optional order[shipto_house_number] Customer 'ship to' house number Up to 32 chars
Optional order[shipto_first_name] Customer 'ship to' first name Up to 32 chars
Optional order[shipto_last_name] Customer 'ship to' last name Up to 32 chars
Optional order[shipto_address1] Customer 'ship to' address line 1 Up to 32 chars
Optional order[shipto_address2] Customer 'ship to' address line 2 Up to 32 chars
Optional order[shipto_city] Customer 'ship to' city Up to 32 chars
Optional order[shipto_state] Customer 'ship to' state 2 chars Must be valid 2 char state code within country
Optional order[shipto_country] Customer 'ship to' country 2 chars Must be valid 2 char ISO country code
Optional order[shipto_zipcode] Customer 'ship to' ZIP/postal code Up to 10 chars
X order[total_subtotal] Line item subtotal Decimal
Optional order[total_discount] Total discounts Decimal
Optional order[total_shipping] Total shipping/handling Decimal
Optional order[total_tax] Total tax Decimal Must match sum of order_item[N][tax] when set
X order[total] Grand total Decimal
Optional order[ship_method] Shipping/delivery method Up to 20 chars
 

Substitute "N" in the parameter name with an incremental line item number(e.g.: 0, 1, 2, 3, etc.).

 
ORDER ITEM
Required Name Value Format Notes
X order_item[N][sku] Item SKU/number Up to 25 chars
X order_item[N][name] Item name Up to 32 chars
X order_item[N][price] Item price (each) Decimal
X* order_item[N][tax] Item tax (each) Decimal *If order[total_tax] is set, Sum must match order[total_tax]
X order_item[N][qty] Item quantity Integer
Optional order_item[N][description] Item description Up to 64kb
Optional order_item[N][details][] Item details Up to 255 chars Supports multiple values per line item, result is serialized into an array
 

Substitute "key" in the parameter name for the unique key (e.g.: "color", etc.).

 
ORDER METADATA
Required Name Value Format Notes
Optional order_metadata[key] Value Up to 255 chars

In addition to or in place of a one-time order/purchase, the Snap* Hosted Payments API also supports creating a recurring subscription scheme. To create a recurring subscription scheme, pass the parameters as part of the HTTP-POST to the checkout interface. Depending on your specific configuration, setting up a subscription can create an order at the time of checkout.

 

Subscription Trial Period

 

A trial period can be included on a subscription by specifying the sub[trial_occurrences] and sub[trial_amount] parameters. For each subscription payment processed in the trial period, the difference between the sub[total] and sub[trial_amount] is added to the sub[total_discount] amount of the resulting order. The sub[trial_occurrences] must not be zero and less than sub[total_occurrences], and the sub[trial_amount] must not be zero and less than sub[total].

 

Subscription Payment Processing (Non-Trial)

 

If the sub[auto_process] parameter is set to true, the Snap* Hosted Payments API automatically attempts to process the subscription payment on the due date. If approved, a new order is created for the subscription payment and an email receipt is sent to the end user.

If the subscription payment process is declined or fails, one of two results can occur:

  1. The subscription payment process is retried at regular intervals until the maximum number of “grace period” days has passed (e.g.: retry every 3 days until 10 days has passed). If the grace period has passed and the process is not successful, the subscription is suspended.
  2. An error message is returned. If the subscription is declined or fails to the point of being considered non-collectable, the subscription is cancelled.
 

In all instances, Snap* Hosted Payments API sends a Merchant Callback message to communicate the results of the attempted payment processing to give the merchant an opportunity to take action (e.g.: customer notification, suspension of access, etc.).

 

Additional Subscription Processing Capabilities:

SUBSCRIPTION DETAIL
Required Name Value Format Notes
X sub[merchant_subscription_id] Merchant Subscription ID Up to 255 chars Must be unique
X sub[interval_length] Length of time between Subscription Payments Integer
X sub[interval_unit] Frequency of Subscription Payments: 'days/weeks/months/years' Fixed values
X sub[start_date] Date to process first Subscription Payment Date Must be at least 1 day in the future
X sub[total_occurrences] Total number of Subscription Payments Integer Specify ‘9999’ for unlimited
X sub[trial_occurrences] Number of occurrences in the Trial Period (if any) Integer See 'Subscription Trial Periods' for more info
X sub[trial_amount] Total amount to bill during the Trial Period (if any) Decimal See 'Subscription Trial Periods' for more info
Optional sub[auto_process] Enable Automatic Payment processing on Snap* Hosted Payment? Boolean See 'Subscription Payment Processing' for more info
Optional sub[billto_company] Customer 'bill to' company Up to 32 chars
Optional sub[billto_first_name] Customer 'bill to' first name Up to 32 chars
Optional sub[billto_last_name] Customer 'bill to' last name Up to 32 chars
X* sub[billto_house_number] Customer 'bill to' house number Up to 32 chars *For international processing
Optional sub[billto_address1] Customer 'bill to' address line 1 Up to 32 chars
Optional sub[billto_address2] Customer 'bill to' address line 2 Up to 32 chars
Optional sub[billto_city] Customer 'bill to' city Up to 32 chars
Optional sub[billto_state] Customer 'bill to' state 2 chars Must be valid 2 char state code within country
Optional sub[billto_country] Customer 'bill to' country 2 chars Must be valid 2 char ISO country code
Optional sub[billto_zipcode] Customer 'bill to' ZIP/postal code Up to 10 chars
Optional sub[shipto_company] Customer 'ship to' company Up to 32 chars
Optional sub[shipto_house_number] Customer 'ship to' house number Up to 32 chars
Optional sub[shipto_first_name] Customer 'ship to' first name Up to 32 chars
Optional sub[shipto_last_name] Customer 'ship to' last name Up to 32 chars
Optional sub[shipto_address1] Customer ship to address line 1 Up to 32 chars
Optional sub[shipto_address2] Customer 'ship to' address line 2 Up to 32 chars
Optional sub[shipto_city] Customer 'ship to' city Up to 32 chars
Optional sub[shipto_state] Customer 'ship to' state 2 chars Must be valid 2 char state code within country
Optional sub[shipto_country] Customer 'ship to' country 2 chars Must be valid 2 char ISO country code
Optional sub[shipto_zipcode] Customer 'ship to' ZIP/postal code Up to 10 chars
X sub[total_subtotal] Line item subtotal Decimal
Optional sub[total_discount] Total discounts Decimal
Optional sub[total_shipping] Total shipping/handling Decimal
Optional sub[total_tax] Total tax Decimal
X sub[total] Grand total Decimal
Optional sub[ship_method] Shipping/delivery method Up to 20 chars
 

Substitute “N” in the parameter names with an incremental line item number (e.g.: 0, 1, 2, 3, etc.).

SUBSCRIPTION ITEM
Required Name Value Format Notes
X sub_item[N][sku] Item SKU/number Up to 25 chars
X sub_item[N][name] Item name Up to 32 chars
X sub_item[N][price] Item price (each) Decimal
X sub_item[N][qty] Item quantity Integer
Optional sub_item[N][description] Item description Up to 64kb
Optional sub_item[N][details][] Item details Up to 255 chars Supports multiple values per line item, result is serialized into an array
 

Substitute “key” in the parameter name for the unique key (e.g.: “color”, etc.).

SUBSCRIPTION METADATA
Required Name Value Format Notes
Optional sub_metadata[key] Value Up to 255 chars

The Snap* Hosted Payments API also allows merchants to establish unstructured payments by securely storing payment account information for future use. Unlike subscriptions, which follow a defined schedule (with consistent items and totals), a token only retains the billing information for a consumer payment method. Merchants can either setup a checkout only option to collect the account information or elect to retain the token with an order/subscription checkout by including the create_token parameter.

   

Token Processing

 

To use (stored payment accounts) tokens, a web service call by the merchant is required. A process_token request to the Snap* Hosted Payment API results in an order creation, receipt emailed to the customer and order details returned to the merchant. The merchant has the option to override the stored billing address with a separate shipping address and any other valuable data as metadata.

 
TOKEN DETAIL
Required Name Value Format Notes
X token[merchant_token_id] Merchant Identifier for the payment account Up to 255 chars Must be unique
Optional token[billto_company] Customer 'bill to' company Up to 32 chars Optional
X* token[billto_house_number] Customer's "bill to" house number Up to 32 chars *For international processing
Optional token[billto_first_name] Customer 'bill to' first name Up to 32 chars
Optional token[billto_last_name] Customer 'bill to' last name Up to 32 chars
Optional token[billto_address1] Customer 'bill to' address line 1 Up to 32 chars
Optional token[billto_address2] Customer 'bill to' address line 2 Up to 32 chars
Optional token[billto_city] Customer 'bill to' city Up to 32 chars
Optional token[billto_state] Customer 'bill to' state 2 chars Must be valid 2 char state code within country
Optional token[billto_country] Customer 'bill to' country 2 chars Must be valid 2 char ISO country code
Optional token[billto_zipcode] Customer 'bill to' ZIP/postal code Up to 10 chars
Optional token[auth_amount] Authorization Amount Decimal
 

Substitute “key” in the parameter name for the unique key (e.g.: “color”, etc.).

 
TOKEN METADATA
Required Name Value Format Notes
Optional token_metadata[key] Value Up to 255 chars

The request and response parameters listed below are common to all ‘actions’:

 
COMMON REQUESTS
Required Name Value Format Notes
X code Merchant’s code Up to 100 chars
X return ‘json’, ‘serialize’, or ‘read’ Fixed values Format to encode the structured response in
X action API “action” to call Up to 32 chars See descriptions of the various actions below
X mac Message Authentication Code (MAC) 32 char hex See below
 
COMMON RESPONSE
Name Value Format Notes
success ‘false’ Boolean
message Error message /description Text
fields One or more offending API parameter names Array

 

REST Checkout API Methods:

Store a checkout for a one-time order, recurring subscription, order plus recurring subscription, or token. The URL value returned can be passed to the end user for use at a later time, or the user can be automatically redirected within the server side script handling the HTTP request.

 
ORDER/SUB/COMBO/TOKEN RESPONSE
Name Value Format Notes
success ‘true’ Boolean
url URL to load the checkout Up to 255 chars Valid anytime, code expires after use

 

Transaction API Actions:

Performs a credit/refund of a previous ‘sale’ transaction. The following parameters should be included, along with the common API parameters:

 
CREDIT REQUEST
Required Name Value Format Notes
X merchant_order_id Merchant’s Order ID Up to 255 chars
X txn_id Payment Transaction ID of the original ‘sale’ Up to 32 chars
Optional amount Amount to credit Decimal Defaults to original transaction amount
 
CREDIT RESPONSE
Name Value Format Notes
success ‘true’ Boolean
status ‘Approved’ Fixed values
txn_id Payment Transaction ID Up to 32 chars

Retrieves the entire subscription object including order information, the number of payment occurrences run, and the next payment due date.

 
SUBSCRIPTION REQUEST
Required Name Value Format Notes
X merchant_subscription_id Merchant Subscription ID Up to 255 chars
  >
SUBSCRIPTION RESPONSE
Name Value Format Notes
success ‘true’ Boolean
subscription Full subscription data object Object

Retrieves a list of merchant order IDs. All merchant’s order IDs are returned if all parameters are omitted.

 
ORDER REQUEST
Required Name Value Format Notes
Optional created[start] Starting order creation date/time Date/Time
Optional created[end] Ending order creation date/time Date/Time
Optional updated[start] Starting order update date/time Date/Time
Optional updated[end] Ending order update date/time Date/Time
Optional merchant_subscription_id Merchant Subscription ID Up to 255 chars
Optional status ‘pending’, ‘paid’, ‘cancelled’, or ‘refunded’ Fixed values
Optional process ‘true’ for orders processed by Snap* Hosted Payment, ‘false’ for orders processed outside (and inserted via the web service) Boolean
 
ORDER RESPONSE
Name Value Format Notes
success ‘true’ Boolean
orders One or more matching merchant_order_id values Array

Retrieves the entire order object either by merchant_order_id or txn_id based on the action requested.

 
GET ORDER REQUESTS
Required Name Value Format Notes
X merchant_order_id Merchant Order ID Up to 255 chars
X txn_id Payment Transaction ID Up to 32 chars
 
GET ORDER RESPONSE
Name Value Format Notes
success ‘true’ Boolean
order Full order data object Object

Retrieves a list of merchant callbacks previously sent. The most recent 20 callbacks are returned if all parameters are omitted.

 
GET CALLBACKS REQUEST
Required Name Value Format Notes
Optional created[start] Starting callback creation date/time Date/Time
Optional created[end] Ending callback creation date/time Date/Time
Optional lastsent[start] Starting last sent date/time Date/Time
Optional lastsent[end] Ending last sent date/time Date/Time
Optional response_code HTTP response code Integer e.g.: 200, 500, 404
Optional start Starting record number Integer Defaults to ‘0’
Optional limit Number of rows to return from starting record number Integer Defaults to ’20’
 

totalCountTotal equals the number of matching callback recordsInteger results. One or more matching callback recordsArray.

 
GET CALLBACKS RESPONSE
Name Value Format Notes
success ‘true’ Boolean

This action creates an order and invokes a payment using the stored payment token. To accommodate HTTP request execution methods that do not support nested objects (e.g.: cURL in PHP), the required nested objects (token_order & token_order_item) require JSON encoding.

 
PROCESS TOKEN REQUEST
Required Name Value Format Notes
X merchant_token_id Merchant Token Id Up to 255 chars
Optional token_order[merchant_order_id] Merchant Order Id Up to 255 chars Auto generated if blank
Optional token_order[billto_company] Customer’s ‘bill to’ company Up to 32 chars Defaults to value from Token
Optional token_order[billto_first_name] Customer ‘bill to’ first name Up to 32 chars Defaults to value from Token
Optional token_order[billto_last_name] Customer ‘bill to’ last name Up to 32 chars Defaults to value from Token
Optional token_order[billto_address1] Customer ‘bill to’ address line 1 Up to 32 chars Defaults to value from Token
Optional token_order[billto_address2] Customer ‘bill to’ address line 2 Up to 32 chars Defaults to value from Token
Optional token_order[billto_city] Customer ‘bill to’ city Up to 32 chars Defaults to value from Token
Optional token_order[billto_state] Customer ‘bill to’ state 2 chars Defaults to value from Token. Must be valid 2 char state code within country
Optional token_order[billto_country] Customer ‘bill to’ country 2 chars Defaults to value from Token. Must be valid 2 char ISO country code
Optional token_order[billto_zipcode] Customer ‘bill to’ ZIP/postal code Up to 10 chars Defaults to value from Token
Optional token_order[shipto_company] Customer ‘ship to’ company Up to 32 chars Defaults to bill to value
Optional token_order[shipto_first_name] Customer ‘ship to’ first name Up to 32 chars Defaults to bill to value
Optional token_order[shipto_last_name] Customer ‘ship to’ last name Up to 32 chars Defaults to bill to value
Optional token_order[shipto_address1] Customer ‘ship to’ address line 1 Up to 32 chars Defaults to bill to value
Optional token_order[shipto_address2] Customer ‘ship to’ address line 2 Up to 32 chars Defaults to bill to value
Optional token_order[shipto_city] Customer ‘ship to’ city Up to 32 chars Defaults to bill to value
Optional token_order[shipto_state] Customer ‘ship to’ state 2 chars Defaults to bill to Token. Must be valid 2 char state code within country
Optional token_order[shipto_country] Customer ‘ship to’ country 2 chars Defaults to bill to value. Must be valid 2 char ISO country code
Optional token_order[shipto_zipcode] Customer ‘ship to’ ZIP/postal code Up to 10 chars Defaults to value from Token
X token_order[total_subtotal] Line item subtotal Decimal
Optional token_order[total_discount] Total discounts Decimal
Optional token_order[total_shipping] Total shipping/handling Decimal
X token_order[total_tax] Total tax Decimal Must match sum of token_order_item[N][tax] when set
X token_order[total] Grand total Decimal
Optional token_order[ship_method] Shipping/delivery method Up to 20 chars
 

Substitute “N” in the parameter names with an incremental line item number (e.g.: 0, 1, 2, 3, etc.).

 
TOKEN ITEM REQUEST
Required Name Value Format Notes
X token_order_item[N][sku] Item SKU/number Up to 25 chars
X token_order_item[N][name] Item name Up to 32 chars
X token_order_item[N][price] Item price (each) Decimal
X token_order_item[N][qty] Item quantity Integer
Optional token_order_item[N][description] Item description Up to 64kb
Optional token_order_item[N][details][] Item details Up to 255 chars Supports multiple values per line item and the result is serialized into an array.
 
TOKEN ITEM RESPONSE
Name Value Format Notes
success ‘true’ Boolean
merchant_order_id Merchant Order ID of the resulting order Up to 255 chars
txn_id Payment Transaction ID of the resulting payment Up to 32 chars
amount Amount of resulting payment Decimal

Retrieves the entire token object.

 
GET TOKEN REQUEST
Required Name Value Format Notes
X merchant_token_id Merchant Token ID Up to 255 chars
 
GET TOKEN RESPONSE
Name Value Format Notes
success ‘true’ Boolean
token Full token data object Object