CreateInvoice
|
Initial Build |
2006.02 |
|
Deprecated Build |
2011.01 |
|
xWEB |
Web Method |
|
Response Type |
XML Results |
Important! CreateInvoice is superseded by WEBCentralizedShoppingCartInsert which should be used instead. CreateInvoice is supported for legacy applications, but integrators are discouraged from using CreateInvoice moving forward. WEBCentralizedShoppingCartInsert offers more capabilities, is easier to implement, and is the preferred way to create invoices and payments.
The CreateInvoice method processes invoices for products that are of product type Merchandise, Subscription, and Publication. Additional functionality will be released in forthcoming releases of xWeb. xWeb will apply the tax product(s) that was setup in the netFORUM product setup. xWeb will need the requesting party to submit the correct shipping product prd_key (or prc_key) in order for the method to process the appropriate shipping charges - this is applied per invoice detail item. The appropriate discount prd_key (or prc_key) will need to be submitted per invoice detail item.
The CreateInvoice method returns the invoice detail items that were created. If the System Option RecognizeRevenueDuringFulfillment is set to "false", then an invoice will be created, if this is set to "true" and a shippable product is purchased, then an order will be created.
The CreateInvoice() method follows the same logic as eWeb for the netFORUM Batch creation process - one batch per day for as many transactions that day. (See: XWeb:CreatePayment#Batch_Selection)
In order to send the payment information in this method, the xWeb service needs to have the correct settings in the web.config file. These settings need to be added to the xWeb/web.config file - without this, the requestor will not be able to process a payment (add the "sectionGroup" element node and the "ECommerceSettings" element node):
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<configSections>
<section name="xWebConfig" type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
<section name="microsoft.web.services2" type="Microsoft.Web.Services2.Configuration.WebServicesConfiguration, Microsoft.Web.Services2, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
<sectionGroup name="ECommerceSettings">
<section name="PayFlowPro" type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
<section name="CyberCash" type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
<section name="PCCharge" type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
</sectionGroup>
</configSections>
<ECommerceSettings>
<PayFlowPro partner="VeriSign" vendor="" username="******" password="******" url="******"/>
</ECommerceSettings>
...
...
...
Unlike the other web methods at xWeb, this method traps all errors within the message transaction and returns the errors in a valid response - the default error-handling for all other messages is to return a soap:fault package as the response. This method doesn't follow the norm as multiple detail items may be submitted and the error(s) is contained for the item, rather than for the collection.
See XWeb:CreatePayment#Exceptions for information about exceptions.
Usage and Examples
Batch Selection
The CreatePayment method will allow you to pass in the batch key through passing a value in inv_bat_key or you may not pass this element which will allow a batch to be auto-selected by the invoice according to the underlying business rules in netFORUM. If the invoice is permitted to select the batch itself, then it will do so by calling Avectra.netForum.Components.AC.ac_utility.GetWebBatchKey which is the method that automatically selects (and initially creates) a web batch for eWeb and xWeb.
Sample Request
The following XML can be generated by the C# code at the end of this page.
Within InvoiceDetail, you may set either the product key (ivd_prc_prd_key) or price key (ivd_prc_key).
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<m:AuthorizationToken xmlns:m="http://www.avectra.com/2005/">
<m:Token>abbc31e0-e26e-4cf9-a0fa-916c005848c4</m:Token>
</m:AuthorizationToken>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:CreateInvoice xmlns:m="http://www.avectra.com/2005/">
<m:InvoiceNode>
<m:InvoiceObjects>
<m:InvoiceObject>
<m:inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</m:inv_cst_key>
<m:InvoiceDetails>
<m:InvoiceDetail>
<m:ivd_prc_prd_key>27AEF5FA-F901-4CFC-AF90-15BEC7659EEE</m:ivd_prc_prd_key>
<m:ivd_qty>3</m:ivd_qty>
<m:InvoiceDetailShipping>
<m:ivd_prc_prd_key>A105052A-9BE2-4E2E-B32D-25E4B93C73B1</m:ivd_prc_prd_key>
</m:InvoiceDetailShipping>
<m:InvoiceDetailDiscount>
<m:ivd_prc_prd_key>B928FC6A-3DF3-4481-9D3E-70338022211E</m:ivd_prc_prd_key>
</m:InvoiceDetailDiscount>
</m:InvoiceDetail>
</m:InvoiceDetails>
</m:InvoiceObject>
</m:InvoiceObjects>
</m:InvoiceNode>
</m:CreateInvoice>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample Response
<?xml version="1.0" encoding="utf-8"?>
<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"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>eb32234e-9e70-437e-b498-bc7998739364</Token>
</AuthorizationToken>
<wsa:Action>http://www.avectra.com/2005/CreateInvoiceResponse</wsa:Action>
<wsa:MessageID>uuid:8703637c-9c05-4d6a-9a5b-18fe5df6e363</wsa:MessageID>
<wsa:RelatesTo>uuid:66ee975b-be07-4c7e-b35e-04737738cc66</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-e271445e-eb6f-4ca6-a91d-d52beb68e38d">
<wsu:Created>2006-10-09T19:01:20Z</wsu:Created>
<wsu:Expires>2006-10-09T19:06:20Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<CreateInvoiceResponse xmlns="http://www.avectra.com/2005/">
<CreateInvoiceResult>
<CentralizedOrderEntryObjects xsi:schemaLocation="http://www.avectra.com/2005/ CentralizedOrderEntry.xsd" recordReturn="7">
<CentralizedOrderEntryObject>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<ivd_key>9955ce0f-0448-4e6d-9b2f-6383bb51e69f</ivd_key>
<bat_key>06507335-9213-46cb-b656-9f90241f5d5c</bat_key>
<ivd_prc_key>d2c5b53f-27c1-4c8a-86b9-1bbd632c6339</ivd_prc_key>
<ivd_cst_ship_key>382454e1-97fd-493c-b12b-e504a926da18</ivd_cst_ship_key>
<ivd_type>Tax</ivd_type>
<inv_code_cp>43352</inv_code_cp>
<ivd_amount_cp>1.14</ivd_amount_cp>
<prc_percent_cp>0.02000000</prc_percent_cp>
<ivd_qty>1.0000</ivd_qty>
<prc_display_name>clienttax</prc_display_name>
<ivd_close_flag>0</ivd_close_flag>
<pay_key/>
<pay_cst_key/>
<pay_trx_date/>
<pyd_type/>
<pay_code/>
<pyd_amount/>
<pin_cc_auth/>
<pin_other_ref_number/>
</CentralizedOrderEntryObject>
<CentralizedOrderEntryObject>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<ivd_key>8909ddb5-d41f-4146-b148-809ec9168c51</ivd_key>
<bat_key>06507335-9213-46cb-b656-9f90241f5d5c</bat_key>
<ivd_prc_key>91290664-9be8-4d03-866c-3335fd8cd655</ivd_prc_key>
<ivd_cst_ship_key>382454e1-97fd-493c-b12b-e504a926da18</ivd_cst_ship_key>
<ivd_type>Shipping</ivd_type>
<inv_code_cp>43352</inv_code_cp>
<ivd_amount_cp>1.80</ivd_amount_cp>
<prc_percent_cp>0.03000000</prc_percent_cp>
<ivd_qty>1.0000</ivd_qty>
<prc_display_name>DHL</prc_display_name>
<ivd_close_flag>0</ivd_close_flag>
<pay_key/>
<pay_cst_key/>
<pay_trx_date/>
<pyd_type/>
<pay_code/>
<pyd_amount/>
<pin_cc_auth/>
<pin_other_ref_number/>
</CentralizedOrderEntryObject>
<CentralizedOrderEntryObject>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<ivd_key>d458dd02-c6cc-4184-b654-949352bd3e93</ivd_key>
<bat_key>06507335-9213-46cb-b656-9f90241f5d5c</bat_key>
<ivd_prc_key>91f559ec-aa60-423c-ad83-f89d85757508</ivd_prc_key>
<ivd_cst_ship_key>382454e1-97fd-493c-b12b-e504a926da18</ivd_cst_ship_key>
<ivd_type>Tax</ivd_type>
<inv_code_cp>43352</inv_code_cp>
<ivd_amount_cp>0.11</ivd_amount_cp>
<prc_percent_cp>0.00200000</prc_percent_cp>
<ivd_qty>1.0000</ivd_qty>
<prc_display_name>CL-Tax</prc_display_name>
<ivd_close_flag>0</ivd_close_flag>
<pay_key/>
<pay_cst_key/>
<pay_trx_date/>
<pyd_type/>
<pay_code/>
<pyd_amount/>
<pin_cc_auth/>
<pin_other_ref_number/>
</CentralizedOrderEntryObject>
<CentralizedOrderEntryObject>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<ivd_key>0fce472e-04d1-4759-8524-9bd2c8156576</ivd_key>
<bat_key>06507335-9213-46cb-b656-9f90241f5d5c</bat_key>
<ivd_prc_key>11107e94-585b-4f7c-9630-5e4b8688dd2c</ivd_prc_key>
<ivd_cst_ship_key>382454e1-97fd-493c-b12b-e504a926da18</ivd_cst_ship_key>
<ivd_type>Tax</ivd_type>
<inv_code_cp>43352</inv_code_cp>
<ivd_amount_cp>1.14</ivd_amount_cp>
<prc_percent_cp>0.02000000</prc_percent_cp>
<ivd_qty>1.0000</ivd_qty>
<prc_display_name>avtax</prc_display_name>
<ivd_close_flag>0</ivd_close_flag>
<pay_key/>
<pay_cst_key/>
<pay_trx_date/>
<pyd_type/>
<pay_code/>
<pyd_amount/>
<pin_cc_auth/>
<pin_other_ref_number/>
</CentralizedOrderEntryObject>
<CentralizedOrderEntryObject>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<ivd_key>beeb9d62-7cb8-43fc-b36e-a0ba0b7cf77c</ivd_key>
<bat_key>06507335-9213-46cb-b656-9f90241f5d5c</bat_key>
<ivd_prc_key>cc9fceeb-3674-4494-8263-1ee0c676e59e</ivd_prc_key>
<ivd_cst_ship_key>382454e1-97fd-493c-b12b-e504a926da18</ivd_cst_ship_key>
<ivd_type>Discount</ivd_type>
<inv_code_cp>43352</inv_code_cp>
<ivd_amount_cp>3.00</ivd_amount_cp>
<prc_percent_cp>0.05000000</prc_percent_cp>
<ivd_qty>1.0000</ivd_qty>
<prc_display_name>5 percent off</prc_display_name>
<ivd_close_flag>1</ivd_close_flag>
<pay_key/>
<pay_cst_key/>
<pay_trx_date/>
<pyd_type/>
<pay_code/>
<pyd_amount/>
<pin_cc_auth/>
<pin_other_ref_number/>
</CentralizedOrderEntryObject>
<CentralizedOrderEntryObject>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<ivd_key>bb2d751f-0322-4b51-9b2c-b28d355c1577</ivd_key>
<bat_key>06507335-9213-46cb-b656-9f90241f5d5c</bat_key>
<ivd_prc_key>19e8d120-ec34-425c-b656-cfbae1f83e0c</ivd_prc_key>
<ivd_cst_ship_key>382454e1-97fd-493c-b12b-e504a926da18</ivd_cst_ship_key>
<ivd_type>Tax</ivd_type>
<inv_code_cp>43352</inv_code_cp>
<ivd_amount_cp>1.14</ivd_amount_cp>
<prc_percent_cp>0.02000000</prc_percent_cp>
<ivd_qty>1.0000</ivd_qty>
<prc_display_name>Avectra Tax</prc_display_name>
<ivd_close_flag>0</ivd_close_flag>
<pay_key/>
<pay_cst_key/>
<pay_trx_date/>
<pyd_type/>
<pay_code/>
<pyd_amount/>
<pin_cc_auth/>
<pin_other_ref_number/>
</CentralizedOrderEntryObject>
<CentralizedOrderEntryObject>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<ivd_key>74289c18-66e3-4924-a0b6-ccdcc81aad67</ivd_key>
<bat_key>06507335-9213-46cb-b656-9f90241f5d5c</bat_key>
<ivd_prc_key>685c0ff5-23b7-4e97-9239-657762e47a68</ivd_prc_key>
<ivd_cst_ship_key>382454e1-97fd-493c-b12b-e504a926da18</ivd_cst_ship_key>
<ivd_type>Product</ivd_type>
<inv_code_cp>43352</inv_code_cp>
<ivd_amount_cp>60.00</ivd_amount_cp>
<prc_percent_cp>0</prc_percent_cp>
<ivd_qty>3.0000</ivd_qty>
<prc_display_name>Office Bags</prc_display_name>
<ivd_close_flag>0</ivd_close_flag>
<pay_key/>
<pay_cst_key/>
<pay_trx_date/>
<pyd_type/>
<pay_code/>
<pyd_amount/>
<pin_cc_auth/>
<pin_other_ref_number/>
</CentralizedOrderEntryObject>
</CentralizedOrderEntryObjects>
</CreateInvoiceResult>
</CreateInvoiceResponse>
</soap:Body>
</soap:Envelope>
Sample Request (C#)
This is an example of a call to CreateInvoice using C#. This code will produce the Sample Request above.
// Call _nfXml.Authenticate() first. Then:
// Use a helper method to create this XML (e.g., using XmlTextWriter)
String strXml = @"
<InvoiceObjects>
<InvoiceObject>
<inv_cst_key>382454e1-97fd-493c-b12b-e504a926da18</inv_cst_key>
<InvoiceDetails>
<InvoiceDetail>
<ivd_prc_prd_key>27AEF5FA-F901-4CFC-AF90-15BEC7659EEE</ivd_prc_prd_key>
<ivd_qty>3</ivd_qty>
</InvoiceDetail>
</InvoiceDetails>
</InvoiceObject>
</InvoiceObjects>";
// Put the XML string into an XmlNode
XmlDocument doc = new XmlDocument();
doc.LoadXml(strXml);
// Consume webservice and capture returned XmlNode
XmlNode node = _nfXml.CreateInvoice(doc);
Case Studies
Below are additional case studies using CreateInvoice. Please feel free to add additional ones.
- xWeb:CreateInvoice Sample1 - This example uses the invoice to send the payment - the response contains the payment information that was processed via PayFlow Pro.
- xWeb:CreateInvoice Sample2 - this second example includes full payment in the invoice request message (baseline invoice).
- xWeb:CreateInvoice Sample3 - This third example uses 3DES encryption on data.
Changing Bill To Address
By default, the bill to address for the Invoice will go to the primary address of the invoice customer as set by inv_cst_key. You can specify a different addresses by doing the following by setting a different cxa_key in <InvoiceObject.ivd_cxa_key>.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>*********************</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:CreateInvoice>
<ns:InvoiceNode>
<ns:InvoiceObjects>
<ns:InvoiceObject>
<ns:inv_cst_key>8513AF59-03D0-4BCD-BE19-2CDE3B912E1C</ns:inv_cst_key>
<ns:pin_apm_key>EB632586-7366-4C62-BB38-31419C1BA71A</ns:pin_apm_key>
<!-- Override default Bill-to Address by setting ivd_cxa_key -->
<ns:ivd_cxa_key>b6370ab9-45e5-486f-85b0-bd5d5041c88b</ns:ivd_cxa_key>
<ns:pin_check_amount>5.05</ns:pin_check_amount>
<ns:inv_autoapply>1</ns:inv_autoapply>
<ns:inv_autoapplypayment>1</ns:inv_autoapplypayment>
<ns:InvoiceDetails>
<ns:InvoiceDetail>
<ns:ivd_prc_key>3c4e8828-9b9d-4ed9-b7f5-12a17d2ba0f4</ns:ivd_prc_key>
<ns:ivd_qty>1</ns:ivd_qty>
<ns:ivd_price>5.05</ns:ivd_price>
</ns:InvoiceDetail>
</ns:InvoiceDetails>
</ns:InvoiceObject>
</ns:InvoiceObjects>
</ns:InvoiceNode>
</ns:CreateInvoice>
</soapenv:Body>
</soapenv:Envelope>
Change Ship To Customer or Address
To change the ship-to customer or ship-to address for a specific line item, set the ivd_cst_key and/or ivd_cxa_key in the <InvoiceDetail> node.