Server Notification API

Guides on how to use CCNow

Server Notification API

Overview

Your account may be configured so that CCNow order alerts are automatically posted to a remote URL, e.g. a script hosted on your web server, when various order events occur in the life cycle of your orders.

CCNow Server Notifications are equivalent to Authorize.Net's Silent Post, PayPal's Instant Payment Notifications (PayPal IPN), WorldPay's Payment Response, Amazon Payments' Instant Order Processing Notifications (IOPN), 2Checkout's Instant Notification Service (2CO INS), Nochex's Automatic Payment Confirmation (APC), or ClickBank's Instant Notification Service.

For example you may receive order alerts when an order has been approved by CCNow payment processing and is ready for you to process and mark shipped in your backroom pending order section. (Currently you receive this event via an email order notice, or by logging into your backroom to view pending orders).

Note that in conjunction with this order push API you may also use the Order Update API to post order actions from your server back to the CCNow server. In particular you can send order "marked shipped" or "cancel" actions to your current pending orders without manually logging into CCNow backroom.

A full list of all types of order events you may receive are listed in next section.

If you would like to pursue this functionality you may configure the options via the Order API screen from your Client Menu backroom login.

top menu ↑

Remote URL Considerations

To use this service you must host a URL which can process the alerts sent from the CCNow servers. It is recommended that the URL is hosted on a secure server and can be addressed via the https secure protocol. It you do not have access to a secure server you may still use Server Notifications but you should not use the "full order detail" option which would result in consumer contact and address information being sent unencrypted over the Internet.

You should also make an attempt to validate any messages received to verify that they come from the CCNow server. In addition to an IP check it is recommended you utilize the "x_ft_hash" parameter described below.

For each alert sent to your hosted URL, you should process appropriately or even ignore certain types of alert types if desired. You should have the program send back an acknowledgment to CCNow server so that we know alert received properly. This is simply just including an "ok" (without parenthesis) at the start of any returned output. If we do not receive this acknowledge token or otherwise receive an non 200 status code from your server we will assume a problem and temporarily block any further alerts being sent to your server. This block will last for a few hours. I.e. if your service is temporarily unable to process incoming alert just send any message not starting with "ok".

Order Alert Types

The following is a complete list of all order events in which you may receive API alerts.
Note that you may choose to receive just a subset of these alerts or all of them.
E.g. a minimal set would be "pending" and "canceled", which would be similar to your current order email notification system.

received:New order just placed by buyer. Note that the order has not yet been processed by CCNow payment or fraud screening system. That is you should not process or ship this order until you receive the "pending" order alert.
vacation_hold:New order placed in vacation hold queue. When you mark return-to-office in your backroom, processing will continue on order.
preorder_hold:New order placed in preorder hold queue. When products in order are available based on the specified preorder hold date, order processing will continue.
getman_hold:New order placed in manual authorization hold queue. When customer provides CCNow credit card image with signature, order processing will continue.
pending:Order has been approved and available for order processing. These are the orders that show up in the Sales / Pending Orders area in your CCNow backroom, and in which you ordinarily first receive an email notice.
test:Test order has been placed.
canceled:Order has been canceled. Note if you previously received a "pending" alert for this order you should not ship the order since it has been marked canceled in CCNow system. If you are configured for "pending" alerts but not "received" alerts, then you will only receive the "canceled" alert if order was canceled after CCNow approval, that is after you received the "pending" alert. If you are also configured for "received" alerts, then you will receive a "canceled" alert if order canceled from any batch processing state prior to approval ("pending" alert).
declined:Payment was declined for this order.
rejected:Order has been rejected due to not meeting CCNow guidelines, consumer fraud, or missing information in order. Note you also receive an email notice for this event.
shipped:Order has shipped; this alert is triggered when you mark order shipped in your backroom or via the order receive API. Note that this alert only is applicable for orders that you mark shipped; for CustomCD orders a separate alert type is used instead.
disc_shipped:For design tool orders, this alert will be sent when the disc service ships product to the customer. Note that for these orders you would not have received a pending order alert since you are not responsible for order shipment.
partial_refund:A partial refund has been issued for this order.
refunded:The order has been fully refunded to consumer.
chargeback:A chargeback has been issued for this order. Note you also receive an email notice for this event.
chargeback_reversal:The chargeback on an order has been reversed and funds put back into your account log.
open_inquiry:An inquiry has been opened on order. Note you also receive an email notice for this event.
reject_inquiry:An inquiry resolution you had entered in your backroom has been rejected.
close_inquiry:An inquiry has been closed on order.
top menu ↑

Order Alert Information

Status only or full details:
For all alert types there are some basic order status information sent in the alerts. These are listed in API field summary below.
In the case of "received" or "pending" order alerts, you may also have your account configured such that a complete set of order information is included in the order alert posting.
This order detail includes buyer shipping and billing address, product information, and complete breakdown of order costing. This is the order information you see when viewing orders in your backroom or email order notices.

Format:

You may choose to receive the order alert content in following formats:

  • named pairs
  • XML stream
Currency considerations:
Note when receiving order alerts for orders that were processed in a non-USD currency, your account may be configured on how to receive order amount fields:
  • order currency: all amount in the order currency, i.e. that which payment made and which is visible to consumer
  • always USD: all amounts converted to USD
  • both: you will receive two sets of amount fields- the order currency amount and the USD amount. This is similar to how you see orders in your backroom.
You may see some examples in section Samples. top menu ↑

Order API Fields

This table includes the basic status information available for all alert types.

Status Alert Fields
FieldAlways Included?Description and Notes
x_clientidYesAccount login ID.
x_storeidYesAccount login ID.
x_storeid and x_clientid are the same unless you are using linked CCNow accounts. In this case x_storeid is account which is associated with web store and x_clientid is account where payment is made.
x_orderidYesCCNow Order Number.
XXX-XX-XXXX format.
x_invoice_numNoClient invoice number.
Only supplied if you are using the third party cart API and are sending your own invoice numbers with orders.
x_orderdateYesTimestamp when order placed.
MM/DD/YYYY hh:mi format. Central standard time.
x_methodYesPayment method.
CC (credit card), PAYPAL, or TEST
x_currency_codeYesThree character currency code:
USD, EUR, AUD, CAD, CHF, DKK, GBP, HKD, INR, JPY, NOK, NZD, SEK, or ZAR
x_amountYesTotal order amount in currency "x_currency_code".
x_amount_usdNoTotal order amount in USD.
Only present if order placed in non-USD currency and your account is configured to receive both order and USD currency amounts.
x_refund_amountNoRefund amount.
Only applicable if alert type is partial or full refund.
x_refund_amount_usdNoIf applicable.
x_statusYesStatus code of order alert:
received, pending, canceled, declined, rejected, partial_refund, refunded, chargeback, chargeback_reversal, open_inquiry, reject_inquiry, or close_inquiry.
x_reasonNoReason for alert. This field may be present for any alert type except "received" or "pending".
x_timestampYesTimestamp when this alert sent.
MM/DD/YYYY hh:mi format. Central standard type.
x_ft_hashYesMD5 hash of parameter values: x_orderid, x_status, x_timestamp, and order API hash key.
The values are joined with a "^" symbol before running thru md5 function. The hash key will be provided when your account is activated for this API and you should keep it private; it will not be sent directly in any alert message. Note that you should use this hash value to authenticate any alert postings you receive to make sure that they are genuine and came from CCNow. See samples page for more details.

This table includes the additional information when alert type is "received" or "pending" AND your account is configured to receive full order details. Note that these field names are the same as third part cart API if you are also using that API.

Full Details - Product Information
FieldAlways Included?Description and Notes
x_numproductsYesNumber of product items lines in order; integer 1 or more.
x_product_sku_NYesProduct identifier code.
"N" is an integer value from 1 to "x_numproducts" to identify multiple product items in order.
x_product_title_NYesTitle of product as it was presented to consumer.
x_product_quantity_NYesQuantity.
x_product_unitprice_NYesUnit price of product in currency "x_currency_code".
x_product_unitprice_usd__NNoUnit price of product in USD.
Only provided if applicable.
x_product_url_NNoReferal URL of product web page (i.e. page hosted on client's web site).
x_product_numoptions_NYesIndicates how many option label/value pairs for this product; integer zero or more.
x_product_option_label_N_MNoProduct option label/value pairs.
"M" is integer from 1 to "x_product_numoptions_N" to mark option number "M" associated with product item "N".
x_product_option_value_N_MNo
Full Details - Customer Billing Name and Address
FieldAlways Included?Description and Notes
x_nameYesName.
x_companyNoCompany; optional.
x_addressYesStreet address.
x_address2NoStreet address line 2; optional.
x_cityYesCity.
x_stateNoTwo-letter code for US, Canada, or India addresses.
x_statenameNoFull state or province name for US, Canada, or India addresses.
x_zipNoPostal or zip code.
Always present for US and Canada addresses. It is optional for other countries.
x_countryYesTwo-letter ISO country code.
x_countrynameYesFull country name.
x_phoneNoPhone number.
x_emailYesEmail address.
Full Details - Customer Shipping Name and Address
FieldAlways Included?Description and Notes
x_ship_to_nameYesName.
x_ship_to_companyNoCompany; optional.
x_ship_to_addressYesStreet address.
x_ship_to_address2NoStreet address line 2; optional.
x_ship_to_cityYesCity.
x_ship_to_stateNoTwo-letter code for US, Canada, or India addresses.
x_ship_to_statenameNoFull state or province name for US, Canada, or India addresses.
x_ship_to_zipNoPostal or zip code.
Always present for US and Canada addresses. It is optional for other countries.
x_ship_to_countryYesTwo-letter ISO country code.
x_ship_to_countrynameYesFull country name.
x_ship_to_phoneYesPhone number.
Full Details - Misc Information, Order Charges, and Discounts
FieldAlways Included?Description and Notes
x_instructionsNoAny special instructions entered by consumer.
x_shipping_labelNoLabel by which shipping charge is displayed to consumer.
x_shipping_methodNoShipping method selected by consumer.
x_shipping_amountNoTotal shipping charge for order.
x_shipping_amount_usdNoIf applicable.
x_discount_labelNoLabel by which an order discount is displayed to consumer.
x_discount_couponNoCoupon code.
x_discount_amountNoTotal order discount amount.
x_discount_amount_usdNoIf applicable.
x_handling_labelNoLabel by which a handling charge is displayed to consumer.
x_handling_amountNoTotal handling charge amount.
x_handling_amount_usdNoIf applicable.
x_tax_labelNoLabel by which a tax is displayed to consumer.
x_tax_amountNoTotal tax amount.
x_tax_amount_usdNoIf applicable.
x_cardholder_nameNoCardholder name when order placed with a credit card.
top menu ↑

Sample Alerts

A few example alerts posting are given below. These examples compare a status-only alert with a full-details alert and named-pair format with xml-stream format.

In all cases the "x_ft_hash" is generated using secret key "12345". E.g. for the first example:

   MD5 function input:397-10-1159^received^12/09/2010 11:14^12345
   MD5 function Output:a56e7eb42d6036a10c1f248aa4b54887


Alert type = received, Details = status only, Format = named pairs
x_amount = 70.68
x_clientid = amylove
x_currency_code = USD
x_fp_hash = a56e7eb42d6036a10c1f248aa4b54887
x_method = TEST
x_orderdate = 12/09/2010 11:08
x_orderid = 397-10-1159
x_status = received
x_storeid = amylove
x_timestamp = 12/09/2010 11:14
Alert type = received, Details = status only, Format = XML stream
data = <x_order>
<x_clientid>amylove</x_clientid>
<x_storeid>amylove</x_storeid>
<x_orderid>397-10-1159</x_orderid>
<x_invoice_num></x_invoice_num>
<x_orderdate>12/09/2010 11:08</x_orderdate>
<x_amount>70.68</x_amount>
<x_currency_code>USD</x_currency_code>
<x_method>TEST</x_method>
<x_status>received</x_status>
<x_reason></x_reason>
<x_timestamp>12/09/2010 11:14</x_timestamp>
<x_fp_hash>a56e7eb42d6036a10c1f248aa4b54887</x_fp_hash>
</x_order>
Alert type = received, Details = full, Format = named pairs
x_address = 123 Main St
x_address2 = Apt #1
x_amount = 70.68
x_city = Los Angeles
x_clientid = amylove
x_country = US
x_countryname = USA
x_currency_code = USD
x_email = jsmith@ibm.com
x_fp_hash = 7c7bbe435a156545cb0e5087204405fb
x_instructions = Please deliver in 5 days.
x_method = TEST
x_name = John Smith
x_numproducts = 2
x_orderdate = 12/09/2010 11:08
x_orderid = 397-10-1159
x_phone = (123) 111-2222
x_product_numoptions_1 = 1
x_product_numoptions_2 = 2
x_product_option_label_1_1 = Size
x_product_option_label_2_1 = Color
x_product_option_label_2_2 = Size
x_product_option_value_1_1 = Mens L
x_product_option_value_2_1 = Pesto
x_product_option_value_2_2 = Medium
x_product_quantity_1 = 2
x_product_quantity_2 = 1
x_product_sku_1 = CS-7112
x_product_sku_2 = BH-7543
x_product_title_1 = Beachy White T-Shirt
x_product_title_2 = Techno GI Shorts
x_product_unitprice_1 = 13.50
x_product_unitprice_2 = 39.00
x_product_url_1 = http://www.ccnow.com/dwh/
x_product_url_2 = 
x_ship_to_address = 123 Main St
x_ship_to_address2 = Apt #1
x_ship_to_city = Los Angeles
x_ship_to_country = US
x_ship_to_countryname = USA
x_ship_to_name = John Smith
x_ship_to_phone = (123) 111-2222
x_ship_to_state = CA
x_ship_to_statename = California
x_ship_to_zip = 90025
x_shipping_amount = 4.68
x_shipping_label = Shipping and Packaging
x_state = CA
x_statename = California
x_status = received
x_storeid = amylove
x_timestamp = 12/09/2010 11:15
x_zip = 90025
Alert type = received, Details = full, Format = XML stream
data = <x_order_details>
<x_clientid>amylove</x_clientid>
<x_storeid>amylove</x_storeid>
<x_orderid>397-10-1159</x_orderid>
<x_invoice_num></x_invoice_num>
<x_orderdate>12/09/2010 11:08</x_orderdate>
<x_amount>70.68</x_amount>
<x_currency_code>USD</x_currency_code>
<x_method>TEST</x_method>
<x_status>received</x_status>
<x_reason></x_reason>
<x_timestamp>12/09/2010 11:15</x_timestamp>
<x_fp_hash>7c7bbe435a156545cb0e5087204405fb</x_fp_hash>
<x_instructions>Please deliver in 5 days.</x_instructions>
<x_shipping_method></x_shipping_method>
<x_cardholder_name></x_cardholder_name>
<x_name>John Smith</x_name>
<x_company></x_company>
<x_address>123 Main St</x_address>
<x_address2>Apt #1</x_address2>
<x_city>Los Angeles</x_city>
<x_country>US</x_country>
<x_countryname>USA</x_countryname>
<x_zip>90025</x_zip>
<x_state>CA</x_state>
<x_statename>California</x_statename>
<x_phone>(123) 111-2222</x_phone>
<x_email>jsmith@ibm.com</x_email>
<x_ship_to_name>John Smith</x_ship_to_name>
<x_ship_to_company></x_ship_to_company>
<x_ship_to_address>123 Main St</x_ship_to_address>
<x_ship_to_address2>Apt #1</x_ship_to_address2>
<x_ship_to_city>Los Angeles</x_ship_to_city>
<x_ship_to_country>US</x_ship_to_country>
<x_ship_to_countryname>USA</x_ship_to_countryname>
<x_ship_to_zip>90025</x_ship_to_zip>
<x_ship_to_state>CA</x_ship_to_state>
<x_ship_to_statename>California</x_ship_to_statename>
<x_ship_to_phone>(123) 111-2222</x_ship_to_phone>
<x_handling_label></x_handling_label>
<x_handling_amount></x_handling_amount>
<x_discount_label></x_discount_label>
<x_discount_code></x_discount_code>
<x_discount_amount></x_discount_amount>
<x_shipping_label>Shipping and Packaging</x_shipping_label>
<x_shipping_amount>4.68</x_shipping_amount>
<x_pmtfee_label></x_pmtfee_label>
<x_pmtfee_amount></x_pmtfee_amount>
<x_tax_label></x_tax_label>
<x_tax_amount></x_tax_amount>
<x_product_list>
<x_product>
<x_product_sku>CS-7112</x_product_sku>
<x_product_title>Beachy White T-Shirt</x_product_title>
<x_product_quantity>2</x_product_quantity>
<x_product_url>http://www.ccnow.com/dwh/</x_product_url>
<x_product_unitprice>13.50</x_product_unitprice>
<x_product_option_list>
<x_product_option>
<x_product_option_label>Size</x_product_option_label>
<x_product_option_value>Mens L</x_product_option_value>
</x_product_option>
</x_product_option_list>
</x_product>
<x_product>
<x_product_sku>BH-7543</x_product_sku>
<x_product_title>Techno GI Shorts</x_product_title>
<x_product_quantity>1</x_product_quantity>
<x_product_url></x_product_url>
<x_product_unitprice>39.00</x_product_unitprice>
<x_product_option_list>
<x_product_option>
<x_product_option_label>Color</x_product_option_label>
<x_product_option_value>Pesto</x_product_option_value>
</x_product_option>
<x_product_option>
<x_product_option_label>Size</x_product_option_label>
<x_product_option_value>Medium</x_product_option_value>
</x_product_option>
</x_product_option_list>
</x_product>
</x_product_list>
</x_order_details>
top menu ↑