Server Notification API
- Overview
- Remote URL Considerations
- Order Alert Types
- Order Alert Information
- Order API Fields
- Sample Alerts
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. |
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.
You may choose to receive the order alert content in following formats:
- named pairs
- XML stream
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.
Order API Fields
This table includes the basic status information available for all alert types.
| Status Alert Fields | ||
| Field | Always Included? | Description and Notes |
| x_clientid | Yes | Account login ID. |
| x_storeid | Yes | Account 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_orderid | Yes | CCNow Order Number. XXX-XX-XXXX format. |
| x_invoice_num | No | Client invoice number. Only supplied if you are using the third party cart API and are sending your own invoice numbers with orders. |
| x_orderdate | Yes | Timestamp when order placed. MM/DD/YYYY hh:mi format. Central standard time. |
| x_method | Yes | Payment method. CC (credit card), PAYPAL, or TEST |
| x_currency_code | Yes | Three character currency code: USD, EUR, AUD, CAD, CHF, DKK, GBP, HKD, INR, JPY, NOK, NZD, SEK, or ZAR |
| x_amount | Yes | Total order amount in currency "x_currency_code". |
| x_amount_usd | No | Total 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_amount | No | Refund amount. Only applicable if alert type is partial or full refund. |
| x_refund_amount_usd | No | If applicable. |
| x_status | Yes | Status code of order alert: received, pending, canceled, declined, rejected, partial_refund, refunded, chargeback, chargeback_reversal, open_inquiry, reject_inquiry, or close_inquiry. |
| x_reason | No | Reason for alert. This field may be present for any alert type except "received" or "pending". |
| x_timestamp | Yes | Timestamp when this alert sent. MM/DD/YYYY hh:mi format. Central standard type. |
| x_ft_hash | Yes | MD5 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 | ||
| Field | Always Included? | Description and Notes |
| x_numproducts | Yes | Number of product items lines in order; integer 1 or more. |
| x_product_sku_N | Yes | Product identifier code. "N" is an integer value from 1 to "x_numproducts" to identify multiple product items in order. |
| x_product_title_N | Yes | Title of product as it was presented to consumer. |
| x_product_quantity_N | Yes | Quantity. |
| x_product_unitprice_N | Yes | Unit price of product in currency "x_currency_code". |
| x_product_unitprice_usd__N | No | Unit price of product in USD. Only provided if applicable. |
| x_product_url_N | No | Referal URL of product web page (i.e. page hosted on client's web site). |
| x_product_numoptions_N | Yes | Indicates how many option label/value pairs for this product; integer zero or more. |
| x_product_option_label_N_M | No | Product 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_M | No | |
| Full Details - Customer Billing Name and Address | ||
| Field | Always Included? | Description and Notes |
| x_name | Yes | Name. |
| x_company | No | Company; optional. |
| x_address | Yes | Street address. |
| x_address2 | No | Street address line 2; optional. |
| x_city | Yes | City. |
| x_state | No | Two-letter code for US, Canada, or India addresses. |
| x_statename | No | Full state or province name for US, Canada, or India addresses. |
| x_zip | No | Postal or zip code. Always present for US and Canada addresses. It is optional for other countries. |
| x_country | Yes | Two-letter ISO country code. |
| x_countryname | Yes | Full country name. |
| x_phone | No | Phone number. |
| x_email | Yes | Email address. |
| Full Details - Customer Shipping Name and Address | ||
| Field | Always Included? | Description and Notes |
| x_ship_to_name | Yes | Name. |
| x_ship_to_company | No | Company; optional. |
| x_ship_to_address | Yes | Street address. |
| x_ship_to_address2 | No | Street address line 2; optional. |
| x_ship_to_city | Yes | City. |
| x_ship_to_state | No | Two-letter code for US, Canada, or India addresses. |
| x_ship_to_statename | No | Full state or province name for US, Canada, or India addresses. |
| x_ship_to_zip | No | Postal or zip code. Always present for US and Canada addresses. It is optional for other countries. |
| x_ship_to_country | Yes | Two-letter ISO country code. |
| x_ship_to_countryname | Yes | Full country name. |
| x_ship_to_phone | Yes | Phone number. |
| Full Details - Misc Information, Order Charges, and Discounts | ||
| Field | Always Included? | Description and Notes |
| x_instructions | No | Any special instructions entered by consumer. |
| x_shipping_label | No | Label by which shipping charge is displayed to consumer. |
| x_shipping_method | No | Shipping method selected by consumer. |
| x_shipping_amount | No | Total shipping charge for order. |
| x_shipping_amount_usd | No | If applicable. |
| x_discount_label | No | Label by which an order discount is displayed to consumer. |
| x_discount_coupon | No | Coupon code. |
| x_discount_amount | No | Total order discount amount. |
| x_discount_amount_usd | No | If applicable. |
| x_handling_label | No | Label by which a handling charge is displayed to consumer. |
| x_handling_amount | No | Total handling charge amount. |
| x_handling_amount_usd | No | If applicable. |
| x_tax_label | No | Label by which a tax is displayed to consumer. |
| x_tax_amount | No | Total tax amount. |
| x_tax_amount_usd | No | If applicable. |
| x_cardholder_name | No | Cardholder name when order placed with a credit card. |
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> |