Transaction Post API
An example transaction post can be viewed here: Example Transaction Post
Account and Security Fingerprint Fields | ||||
Field | Required | Value | Notes | |
x_login | Required | varies by client | 12 | CCNow Client ID |
x_version | Required | 1.0 | API version number. | |
x_fp_sequence | Required | Client specified sequence number to ensure that each transaction is unique. E.g. it could be an invoice number or a random number. | ||
x_fp_arg_list | Required |
This is a list of field names and order in which the field values are passed into the MD5 hashing algorithm to generate the transaction fingerprint hash. At a minimum the following fields should
be included:
| ||
x_fp_hash | Required | This is the fingerprint generated using an MD5 hashing algorithm on the client's secret cart-activation key and the fields listed in x_fp_arg_list. The field values are concatenated and separated by the "^" character; the order of field values has to match the order of field names in x_fp_arg_list. | ||
Product Information | ||||
Field | Required | Value | Max Length | Notes |
x_product_sku_N | Required | String comprising letters, numbers, and/or hyphen only | 30 | Unique product identifier. "N" is an integer value 1.. to identify multiple product items in shopping cart, i.e. x_product_sku_1 |
x_product_title_N | Required | 500 | Brief title of product as it was presented to consumer. | |
x_product_quantity_N | Required | Integer | ||
x_product_unitprice_N | Required | Money | Unit price of product in currency of transaction. | |
x_product_url_N | Required | 200 | Send fully qualified URL that links to page that presents details of the product; preferably the same URL as viewed by the consumer. | |
x_product_ffurl_N | Optional | 200 | Send fully qualified URL that provides a download link to the customer for a digital product at the time of sale. Only used for Auto-fulfillment/real-time processing orders. | |
x_product_ffmsg_N | Optional | 200 | Customer message to be displayed with the fulfillment URL for real-time/auto-fulfillment orders. | |
x_product_option_label_N_M | Optional | 30 | Send multiple product option label/value pairs, e.g. Color:Red. M is integer 1.. to mark option number "M" associated with product item "N". | |
x_product_option_value_N_M | Optional | 500 | ||
Customer Billing Name and Address
| ||||
Field | Required | Value | Max Length | Notes |
x_name | Required | 100 | ||
x_company | Optional | 100 | ||
x_address | Required | 100 | ||
x_address2 | Optional | 100 | ||
x_city | Required | 100 | ||
x_state | Required* | 2-letter US state or Canada province | 2 | *only required for US/Canada addresses; otherwise ignored. |
x_statename | Optional* | 2 | State, region, or province; only used for countries other that US or Canada. | |
x_zip | Required* | 30 | *only required for US/Canada addresses; otherwise optional. | |
x_country | Required | 2-letter ISO country code | 2 | permitted countries non-permitted countries |
x_phone | Required | 30 | full 10 digit number required for US addresses; min 6 digits required otherwise. | |
x_email | Required | 100 | Client should usually require consumer to type in twice since this is most important piece of consumer info. | |
Customer Shipping Name and Address
| ||||
Field | Required | Value | Max Length | Notes |
x_ship_to_name | Required | 100 | ||
x_ship_to_company | Optional | 100 | ||
x_ship_to_address | Required | 100 | ||
x_ship_to_address2 | Optional | 100 | ||
x_ship_to_city | Required | 100 | ||
x_ship_to_state | Required* | 2-letter US state or Canada province | 2 | *only required for US/Canada addresses; otherwise ignored. |
x_ship_to_statename | Optional* | 2 | Region, county, or province; only used for countries other that US or Canada. | |
x_ship_to_zip | Required* | 30 | *only required for US/Canada addresses; otherwise optional. | |
x_ship_to_country | Required | 2-letter (ISO 3166-1 alpha-2) country code | 2 | permitted countries non-permitted countries |
x_ship_to_phone | Optional | 30 | ||
Misc Information, Charges, and Discounts | ||||
Field | Required | Value | Max Length | Notes |
x_invoice_num | Optional | 30 | You may optionally pass an invoice number for the transaction; note however that CCNow order system generates its own identifer. | |
x_instructions | Optional | 500 | This is similar to the "special instructions" field in the hosted CCNow shopping cart. | |
x_shipping_label | Optional | 50 | If applicable; e.g. "Shipping:", "Shipping & Handling:", etc. | |
x_shipping_amount | Optional | Money | If applicable; enter in format appropriate to the transaction currency. | |
x_shipping_method | Optional | 50 | If applicable; e.g. "Air", "Ground", etc. | |
x_discount_label | Optional | 50 | If applicable; e.g. "Discount coupon: XXX". | |
x_discount_coupon | Optional | 20 | If applicable; alphanumeric string only. | |
x_discount_amount | Optional | Money | ||
x_tax_label | Optional | 50 | If applicable; e.g. "EU VAT" | |
x_tax_notes | Optional | 50 | If applicable; addition notes displayed under the tax amount e.g. an actual EU VAT registration number. | |
x_tax_amount | Optional | Money | ||
x_language | Optional | 2-letter language code (ISO 639-1). NOTE: sometimes differs from the ISO 3166-1 two letter code for the country in which language is spoken | Shopping cart language: en=English, de=German, es=Spanish, fr=French, it=Italian. | |
Transaction Data | ||||
Field | Required | Value | Max Length | Notes |
x_amount | Required | Money | x_amount is the total transaction amount for the order. If the currency code is non-USD, then the consumer's credit or debit card will be charged in that currency for Visa and MasterCard; for other card types, the consumer's credit card will be charged in USD at a conversion rate determined at time of order placement. | |
x_currency_code | Required | 3-letter currency code (ISO 4217). AUD, GBP, CAD, CHF, DKK, EUR, HKD, INR, JPY, NOK, NZD, SEK, USD, ZAR |
||
x_method | Required | CC PAYPAL TEST NONE | Payment method: CC - Credit-Card PAYPAL - PayPal TEST - Test Order NONE - CCNow hosted checkout page used by customer to select payment type. | |
Subscription/Recurring Billing
| ||||
Field | Required | Value | Max Length | Notes |
x_subscription_type | Optional | "Auto", "A", "Manual", or "M" |
Auto Recurring: This will automatically rebill the consumer at the specified frequency and will create a new order each time which you receive in your pending orders. Manual Recurring: The consumer will receive an email notification at the specified frequency, in which they will be instructed to authorize a renewal which creates a new order. If field not received, it is assumed to be "Auto". | |
x_subscription_freq | Optional | Specify the subscription frequency with a number appended with "D" (days), "W" (weeks), "M" (months), or "Y" (years). E.g. "10D" is 10 day frequency, "2M" is 2 month frequency. Minimum allowed frequency is 7 days. Note, if field is not supplied, then order is not a subscription order. | ||
x_subscription_max | Optional | To limit the number of recurring orders, enter a value here. If not specified, the recurring orders will continue indefinitely. |