2Checkout will be releasing has released a new beta version of our Instant Notification Service (INS) later this week.
This new version has streamlined message parameter definitions, and more INS messages than the original preview version.
Messages in this release:
- Order Created
- Fraud Status Changed
- Shipping Status Changed
- Invoice Status Changed
- Refund Issued
- Recurring Installment Success
- Recurring Installment Failed
- Recurring Stopped
- Recurring Complete
- Recurring Restarted
A full set of updated, streamlined and simplified documentation is posted online will be posted online soon. These documents provide detailed information and multiple examples of the parameters that are passed back for each message.
In this release, all messages will share one of 2 parameter set definitions: Item level or Invoice level. Additionally, some parameters have been added, including:
- customer_ip
- customer_ip_country
- ship_status
- ship_tracking_number
Detailed descriptions of the new parameters will be provided in the new documentation. Release details and new documentation will be posted online soon; we’d like to thank everyone again for their participation and feedback!
Please Note: The INS Opt-in can only be found within our new Vendor Area, located here. Use your regular username & password from the old Vendor Area to login.
Also, keep in mind that suppliers can make use of the Instant Notification Service Simulator within the developers.2Checkout area as an additional way to test their INS scripts.
Originally posted April 22, 2008
17 Comments »
+0
-0
good
+0
-0
If I opt-in to use the INS notifications, I will still receive the usual passback parameters that are sent with the Direct Return feature, correct?
Also, is it safe for us to go ahead and start coding our scripts to use this? I know it’s Beta, but I want to get a jump start on it, but don’t want to code a whole bunch and have it end up being completely changed later on either. Any guidance on this is appreciated.
+0
-0
A lot of the INS parameters use the same information that is received from Direct Return, but they may have different parameter names or extra parameters that are not included in the original Direct Return passback (such as the current sale status or recurring installment number).
We hope to keep the current parameters through upcoming updates to the INS system, however it cannot be guaranteed that the parameters will not change.
+0
-0
Enrollment in INS will not affect Direct Return.
The INS parameters in this latest release are expected to be fairly stable. A few minor changes to the User Guide will be released tomorrow, specifically:
* auth_exp will be marked optional because when a sale has been cancelled in full it is no longer available
* bill_state and bill_postal_code will be marked optional because there are some valid foreign addresses which do not contain these items
2CO’s current plans for INS involve incorporating vendor feedback, and evaluating possible additions to the INS system. Basically, unless there is a problem with the message structures as stated today, the only reason they would change would be to add additional useful information to the messages.
+0
-0
On the INS User Guide v1.1, under the page all about the “Recurring Installment Success” Message, it says the following:
“Please note this message will be identical (except for timestamp) whether it is the first attempt or a retry.”
I’m not quite sure I understand what this means??? If the recurring installment is a success (which this message is for), how would there ever be a retry? Any further elaboration on this would greatly be appreciated.
Also, on a related note…
Is there ANY CIRCUMSTANCE where two INS messages sent from 2CO would share the same message_id? Because I am setting up a MySQL database to hold all these parameters, and as of right now I have the message_id parameter set to be UNIQUE. In other words, no two INS events can share the same message_id.
Thank you for your help.
+0
-0
This means that should a recurring installment fail and the installment need to be re-billed, the message for that successful billing would be the same as one received for an installment that bills successfully on the first attempt.
The message_id will always be unique on a per-vendor level. The first INS message sent to each vendor will start at ‘1′ and increment from there. As long as you are not storing passbacks from multiple vendors in the same table, you should not encounter non-unique message IDs. The only time the message_id may not be unique is if the INS system attempts to retry sending a message that has already been received.
+0
-0
Could you please describe the REFUND_ISSUED message type to me?
item_type_# is set to refund for this message, from what I understand. How can I tell how much has been refunded, is that given in item_list_amount_#?
Also, let’s say a sale has two identical items. For each item, I provide the customer with an on-line service, customisable etc. Then one of those items gets refunded. How can I distinguish which item has been refunded?
And how about partial refunds for “no specific item”? How would such an INS call be made?
+1
-0
The amount that was refunded will be provided in the item_usd_amount_ parameter.
If the product IDs are identical, there would be no way to distinguish which was refunded in the notification.
With partial refunds, item_id_ will not be sent with the INS. The amount for the refund will be provided item_usd_amount_ parameter.
+0
-0
Thanks for the clarification.
Your feature guide states thate item_id_ is a required field for message_type=REFUND_ISSUED.
+1
-0
Thank you for pointing this error out. We will address this issue in our documentation.
+0
-0
I was advised over the LiveHelp chat that the INS should work even if the order is in “Demo” mode (demo=”Y”).
Had somebody any positive experience on that?
I have prepared the script for the INS notifications and it works fine when I send the parameters to it with my another script.
But when I try to process the demo transaction on my website nothing seems to come back through INS.
Any advice would be appreciated.
Thanks in advance.
+0
-0
Hello Crow – I apologize for the incorrect information you were provided. Demo sales will not trigger any INS posts to your scripts. You will need to place a live sale to test the different INS messages. If you just wish to test the new order created message you can place a live test sale and cancel the sale after it has been placed so no funds are removed from your credit card. If you have any other INS questions please contact our technical support team.
+0
-0
I found the pdf file with the IPN explained but it has one flaw that makes it difficult to develop for this feature.
For each type of message, there isn’t a clear and full list of the main status options.
Take FRAUD_STATUS_CHANGED for instance. There is just one example showing fraud_status=pass but I don’t know if there are other messages that could arrive with fraud_status=pending or fraud_status=fail (I guess the last one is a banker.
On INVOICE_STATUS_CHANGED for instance, the file tells us most orders go from
‘approved’ to ‘pending’ to ‘deposited’ but this suggests some orders might have some other things posted and without full information, it is difficult to write proper code.
What is needed is a full list of the options for each of the relevant xyz_status fields. These should be explained.
In summary, I don’t want to write code to process xyz_status=1 or 2 or 3 when there might be 4 & 5.
+0
-0
All possible values for each parameter are listed in the description column of the documentation. FRAUD_STATUS_CHANGED and INVOICE_STATUS_CHANGED are not parameters, they are possible values for the message_type parameter. Each message type sends a specific set of parameters that is listed in the “Parameters by message” section of the documentation. The possible values for each parameter are listed in the descriptions for instance fraud_status (pass, fail, or wait) and invoice_status (approved, pending, deposited, or declined).
+0
-0
Thanks.
I understand that FRAUD_STATUS_CHANGED and INVOICE_STATUS_CHANGED are not parameters.
Now regarding the main parameters, I downloaded Rev 1.1 of the INS User Guide and can’t see where the possible values are listed.
On Page 11 of the PDF dealing with Fraud Status for instance, all I can find is “fraud_status=pass” which is highlighted in yellow.
Can you please point me to the relevant part or document if I got the wrong one? I just downloaded it from this site a couple of days ago.
+0
-0
The page you are referring to only provides an example INS post for the Fraud Status Changed message type. The information you are looking for can be found on page 4 under INS parameter descriptions and formats.
+0
-0
Found it. Thanks.