You are here:

WEBCentralizedShoppingCartInsert

Initial Build	2008.1
xWEB	Web Method
Response Type	object

This method can be used to insert a new invoice, along with a payment (optionally), based on the contents of a Shopping Cart Object.

Parameters

oCentralizedOrderEntry (Shopping Cart Object). An Order Entry object.

Response

Shopping Cart Object

Applying Credit Card Payment

If you want to apply a credit card payment, set the following properties in the <Payment_Info> node:

pin_cc_cardholder_name - the name as it appears on the credit card.
pin_cc_number - the clear text credit card number. Since xWeb is on TSL it will be encrypted.
pin_cc_security_code - the credit card security code.
pin_cc_expire - the expiration date in exactly YYYY/MM format, eg 2011/08. Include the leading zero for months January (01) through September (09).
pin_apm_key - the key of the Payment Method. Visa, MasterCard, Amex, etc. You can get a list of these to put on a payment page by calling WEBCentralizedShoppingCartGetPaymentOptions.
pin_check_amount - the amount to apply. You can determine the full calculated amount of the invoice from <Invoice.inv_nettotal>. Technically, you can apply less than that amount and netFORUM will automatically apply the payment toward the various line item(s) in the order according to internal netFORUM rules about how to apply a partial payment. (Note: don't be concerned that this property name, and then next property below, has the word "check" in it; these properties are valid for any payment type including credit cards despite the name.)
pin_check_amountSpecified - set to true.

In the <Invoice> node set the following properties:

inv_autoapply - set to 1.
inv_autoapplypayment - set to 1.

See XWeb_eCommerce_SDK for a link to a PDF document showing a case study with this.

Terms Invoice With No Payment

If you want to create a terms invoice with no payment, then set the following three elements to these values:

Invoice.inv_orig_trans_type to terms.
Invoice.inv_ait_key - This is the value for the Invoice Terms (such as Net 30 days) set to the appropriate value of ac_invoice_terms.ait_key. You can run GetQuery to discover these values. You'll probably want to do this offline and then create a constant that stores the value you want to set. You'll likely have your application set this value instead of having the end user specify the terms.
Invoice.inv_autoapplypayment - set to 0. This property will stop the invoice from trying to apply a payment.

You do not need to set any values in the Payment or Payment_Info elements.

Sample Request

Shortened for brevity.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>xxxxxxxxxxxxx</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:WEBCentralizedShoppingCartInsert>
<ns:oCentralizedOrderEntry>
          [[Shopping Cart Object]] 
</ns:oCentralizedOrderEntry>
</ns:WEBCentralizedShoppingCartInsert>
</soapenv:Body>
</soapenv:Envelope>

Sample Response

Shortened for brevity.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AuthorizationToken soap:mustUnderstand="1" xmlns="http://www.avectra.com/2005/">
<Token>8aa23d04-d2f9-45bc-9ff5-f187953c990f</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<WEBCentralizedShoppingCartInsertResponse xmlns="http://www.avectra.com/2005/">
<WEBCentralizedShoppingCartInsertResult xsi:type="CentralizedOrderEntryType">
</WEBCentralizedShoppingCartInsertResult>
</WEBCentralizedShoppingCartInsertResponse>
</soap:Body>
</soap:Envelope>

FAQ

Selecting a batch

Q. How can I set the Batch that the order will go into?

A. At this point, netFORUM will select the batch automatically based on logic in Avectra.netForum.Components.AC.ac utility.GetWebBatchKey. It is not possible to override this by setting the values in inv_bat_key or other properties in the request.

Although this might not be ideal, one possible work-around is to go ahead and insert the order, and then follow that by updating the batch for the newly created invoice and payment. You can do this by calling UpdateFacadeObject for both the Payment (pay_bat_key) and the Invoice (inv_bat_key) to switch both transactions to the batch you would prefer. To avoid slowing down the main processing, you might want to decouple this operation with the order processing and have it run separately in a batch process or some other asynchronous process.

There should be no issues with doing this, as a staff user in iWeb can do the exact same step manually by editing the invoice or payment and select any non-closed, non-exported, non-hidden batch for which the user have the proper Batch Group Access security credentials.

FOLLOWUP - While manually updating the batch seems like a reasonable suggestion, it appears the process would break if there were no current batch open for the target business unit - as in the case of the first transaction for the daily Web batch. For transactions using the "normal" processes, a new batch is automatically created when needed. But in this case, updating the batch on a newly created invoice and payment, the target batch MUST already exist.

Applying Payment with PayPal Express

To apply a payment via PayPal Express, your application will need to get a Token and PayerID from the buyer using the buyer's PayPal account. You'll need to get this by using the PayPal Express API independently of netFORUM as this interaction must occur on the client-side (e.g. an end user must authenticate to PayPal through a user interface that you engineer into your application in conjunction with the PayPal API). Then, in your request to WEBCentralizedShoppingCartInsert, you must supply the following values:

pin_paypaltoken - The timestamped token value that was returned in the SetExpressCheckout response and passed in the GetExpressCheckoutDetails request. You'll need to get this Token by calling the PayPal Express API.
pin_paypalpayerid - Unique PayPal buyer account identification number as returned in the GetExpressCheckoutDetails response. You'll need to get this by calling the PayPal Express API.
pin_apm_key - You will also need to use a Payment Method with a Payment Type that is PayPal.

Note: The first two properties are Virtual Fields that are used in-memory during runtime purely to send the payment information to the gateway, but are not stored in the netFORUM database.

Inserting Order with external electronic payment

If the external system is managing the electronic payment (i.e. you do not want netFORUM to authorize a credit card) then you still need to apply a payment to pay down the invoice, but you don't want to double-charge the card.

To do this, in iWeb first create a Payment Method that is similar to a cash payment method, and code your external application to use that payment method by setting the <pin_apm_key> with its value. Configure the payment method as follows:

Name the payment method something like External Credit Card Payment (or whatever makes sense to you).
Set the payment type to other
Select both the available internally and available on centralized shopping cart checkboxes.
Select the cash account which these transactions should debit.

In xWeb, you should not set the values of any of the "cc" fields (pin_cc_number, pin_cc_cardholder_name, etc.) in the payment, since these fields are used only for actual credit card transactions. Instead, you may use the "reference number" field pin_other_ref_number or pay_notes to include any relevant information about the transaction, such as a masked CC number (for security reasons, do not send over the complete credit card number) or authorization code, that will help you reference the transaction.

By setting the payment type to other, when the payment record is added, netFORUM will not attempt to do any electronic payment transactions, and will treat the payment like a cash/check payment. If a user in netFORUM tries to void or return the payment, it will of course not refund the money back to the credit card, so adjust your organization's SOPs accordingly.

Applying payment with token

To apply a payment with a stored payment information (aka a token from an electronic payment gateway), then you must supply a value to this property:

Payment_Info.pin_cpi_key.

To apply payment immediately, set:

cart.InstallmentBilling.ord_auto_pay = 1;
cart.InstallmentBilling.ord_auto_paySpecified = true;

Since the token contains all the information about the payment method, you do not need to set any of the other pin fields described in Applying_Credit_Card_Payment.

To get a cpi_key for a particular customer, you can run a GetQuery against the CustomerPaymentInfo object to select tokens for a customer, and filter on cpi_cst_key (the Customer Key) for the given customer.

If you have an application that gets a new token directly from the gateway, independently of netFORUM, you first must insert that token into netFORUM via InsertFacadeObject for the CustomerPaymentInfo object, so that the token will already be linked to the customer prior to calling WEBCentralizedShoppingCartInsert. Note that if, for any reason, WEBCentralizedShoppingCartInsert does not succeed, there is no downside to having the token with the customer.

As a best practice, we recommend any applications that directly interact with the gateway use a different API user account from the one that netFORUM uses. The API user will be connected to the same merchant account(s) but having different API users will assist with diagnostics and understanding the origin of gateway requests.