CreatePayment

Initial Build	2006.02
Deprecated Build	2011.01
xWEB	Web Method
Response Type	XML Results

Important! CreatePayment is superseded by WEBCentralizedShoppingCartInsert. CreatePayment is supported for legacy applications, but integrators are discouraged from using CreatePayment moving forward. WEBCentralizedShoppingCartInsert offers more capabilities, is easier to implement, and is the preferred way to create invoices and payments.

This example CreatePayment() method request accompanies the CreateInvoice method request example for an invoice (not an order) - please refer to the CreateInvoice example to understand the invoice items that were requested for which this method is used to submit payment.

The CreatePayment() operates on Verisign submitted payments, meaning that this method can process credit card payments, ACH payments, and telecheck payments. The apm_key (Payment Method key) must be submitted in the CreatePayment() request message - this key is retrievable out-of-band and must be coordinated at implementation as these keys will be different for every client.

The CreatePayment() method returns the payment detail items that were created and includes the reference number for the charge that was submitted to Verisign.

The CreatePayment() method follows the same logic as eWeb for the netForum Batch creation process - one batch per day for as many transactions that day. See Batch Selection below for details.

In order to send the payment information in this method, the xWeb service needs to have the correct settings in the /xweb/web.config file. See CreateInvoice for details.

Parameters

XmlNode or 3DES encrypted string.

Be sure to set the total payment amount in an element for pin_check_amount. Don't be thrown off by the word "check" in this element's name -- this element is used for all payment amounts including credit cards.

Response

Returns the inserted key(s) for the payment

Exceptions

As described in XWebException, beginning in 2007.01, this method returns errors as exceptions to be consistent with other xWeb methods. For example, here is an error message for an invalid credit card. Note that the actual message is in the <MessageDetail> node within the XWebException.

<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:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>System.Web.Services.Protocols.SoapException: An error occurred
   at Avectra.netForum.xWeb.xWebSecure.netForumXMLSecure.CreatePayment(XmlNode oNode) in c:\Inetpub\wwwroot\nf2_2007_01_03\xWeb\App_Code\Secure\netForumXML.asmx.cs:line 1168</faultstring>
<faultactor>http://localhost/nf2_2007_01_03/xweb/secure/netForumXML.asmx</faultactor>
<detail>
<SystemExceptionInfo xmlns="http://www.avectra.com/2005/">
<XWebException>
<Message>An error occurred</Message>
<MessageDetail>Invalid Credit Card Expiration Date. Invalid expiration date: 1206</MessageDetail>
<UserMessage/>
<Number>199</Number>
<Source>xWebClasses</Source>
<Class/>
<Library/>
<Method/>
<Line>0</Line>
<StackTrace>at Avectra.netForum.xWeb.FacadeData.CreatePaymentService(XmlNode InvoiceNode) in C:\Inetpub\wwwroot\nf2_2007_01_03\netForum2WebServices\xWebClasses\FacadeWebService.cs:line 3824
   at Avectra.netForum.xWeb.xWebSecure.netForumXMLSecure.CreatePayment(XmlNode oNode) in c:\Inetpub\wwwroot\nf2_2007_01_03\xWeb\App_Code\Secure\netForumXML.asmx.cs:line 1147</StackTrace>
<SQLCommand/>
<ErrorType>GeneralError</ErrorType>
<ErrorKey>88fce459-6860-4ffc-a096-0b20be275a88</ErrorKey>
<Errors/>
</XWebException>
</SystemExceptionInfo>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

Batch Selection

Similar to xWeb:CreateInvoice, the payment batch may be selected by the calling program by setting the value of the element pay_bat_key. Alternately, the calling program may not pass this element and have the batch selected automatically by the underlying business rules in netFORUM.

If pay_bat_key is not selected, then xWeb will do the following logic:

If the system option COEBatchByPaymentMethod is set to true then a batch will be selected based on the Payment Method's batch suffix using the batch naming convention for eWeb and xWeb as described in Avectra.netForum.Components.AC.ac_utility.GetWebBatchKey.

Otherwise, if the system option COEBatchByPaymentMethod is set to false then a web batch will be created but without the payment method suffix.

Credit Card Encryption

The credit card number supplied in the <pin_cc_number> xml node is encrypted with Triple DATA ENCRYPTION STANDARD (DES). You can use baseline TripleDesCBCSymmetricEncrypt and TripleDesCBCSymmetricDecrypt methods in the Avectra.netForum.xWeb.xWebSecure.Crypto class.

The class file is in the following reference dll:

netFORUM 2.0: xWeb/bin/xWebClasses.dll
netFORUM 1.0: xWeb/bin/xWeb.dll

This is a VB.NET example:

            Dim xWebCrypto As New Avectra.netForum.xWeb.xWebSecure.CryptoCCNumber_Encrypted = xWebCrypto TripleDesCBCSymmetricEncrypt(CCNumber)

If the xWebClasses.dll is unavailable or the baseline encryption methods are not accessible, then you'll need to use a 3DES encryption method available in a library for the language you're working with or create your own implementation of the standard. You'll need to ensure that netFORUM is using the same encryption key and initial vector as your encryption function. The encryption key and initial vector used to encrypt and decrypt data in netFORUM can be set in the /xweb/web.config file. The <AppSetting> section of the configuration file needs the keys <activeTripleDESKey> and <activeTripleDESInitialVector>. The key and vector values are both stored as Base64 strings.

Credit Card Expiration Date

Avectra requires that all credit card expiration dates be provided in the format (YYYY/MM) and the month must use a leading zero if it's only one digit (eg. 2012/06).

Sample Request

<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>dc74d090-9cc1-4367-ae05-18f7a567b55f</m:Token>
</m:AuthorizationToken>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:CreatePayment xmlns:m="http://www.avectra.com/2005/">
<m:oNode>
<m:PaymentObjects>
<m:PaymentObject>
<m:pay_cst_key>382454e1-97fd-493c-b12b-e504a926da18</m:pay_cst_key>
<m:pin_apm_key>C05EA2DC-064B-450E-9673-60D6817EDAE2</m:pin_apm_key>
<m:pin_cc_number>vVBaWKeguXwDkZO02upHow6Ag04crlTm</m:pin_cc_number>
<m:pin_cc_cardholder_name>Test Name</m:pin_cc_cardholder_name>
<m:pin_cc_expire>2006/12</m:pin_cc_expire>
<m:PaymentDetails>
<m:PaymentDetail>
<m:pyd_ivd_key>9955ce0f-0448-4e6d-9b2f-6383bb51e69f</m:pyd_ivd_key>
<m:pyd_amount>1.14</m:pyd_amount>
</m:PaymentDetail>
<m:PaymentDetail>
<m:pyd_ivd_key>8909ddb5-d41f-4146-b148-809ec9168c51</m:pyd_ivd_key>
<m:pyd_amount>1.80</m:pyd_amount>
</m:PaymentDetail>
<m:PaymentDetail>
<m:pyd_ivd_key>d458dd02-c6cc-4184-b654-949352bd3e93</m:pyd_ivd_key>
<m:pyd_amount>0.11</m:pyd_amount>
</m:PaymentDetail>
<m:PaymentDetail>
<m:pyd_ivd_key>0fce472e-04d1-4759-8524-9bd2c8156576</m:pyd_ivd_key>
<m:pyd_amount>1.14</m:pyd_amount>
</m:PaymentDetail>
<m:PaymentDetail>
<m:pyd_ivd_key>bb2d751f-0322-4b51-9b2c-b28d355c1577</m:pyd_ivd_key>
<m:pyd_amount>1.14</m:pyd_amount>
</m:PaymentDetail>
<m:PaymentDetail>
<m:pyd_ivd_key>74289c18-66e3-4924-a0b6-ccdcc81aad67</m:pyd_ivd_key>
<m:pyd_amount>57.00</m:pyd_amount>
</m:PaymentDetail>
</m:PaymentDetails>
</m:PaymentObject>
</m:PaymentObjects>
</m:oNode>
</m:CreatePayment>
</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>e7c8c813-6751-49c9-ad6b-46241f2979d4</Token>
</AuthorizationToken>
<wsa:Action>http://www.avectra.com/2005/CreatePaymentResponse</wsa:Action>
<wsa:MessageID>uuid:afc04778-8cb4-4f76-b782-86b917be3d1d</wsa:MessageID>
<wsa:RelatesTo>uuid:076c795d-2842-496e-8923-7d6dc1222a8c</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-e336504b-1a7b-48d8-af75-b9e97c153c62">
<wsu:Created>2006-10-09T19:07:19Z</wsu:Created>
<wsu:Expires>2006-10-09T19:12:19Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<CreatePaymentResponse xmlns="http://www.avectra.com/2005/">
<CreatePaymentResult>
<PaymentObjects xsi:schemaLocation="http://www.avectra.com/2005/ Payment.xsd" recordReturn="6">
<PaymentObject>
<pay_key>f4f0a480-aaf5-4a61-8250-ff8510af2024</pay_key>
<pay_cst_key>382454e1-97fd-493c-b12b-e504a926da18</pay_cst_key>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<ivd_key>9955ce0f-0448-4e6d-9b2f-6383bb51e69f</ivd_key>
<ivd_closed_flag>1</ivd_closed_flag>
<pay_trx_date>10/9/2006 12:00:00 AM</pay_trx_date>
<pyd_type>payment</pyd_type>
<pay_code>32485</pay_code>
<pyd_amount>1.14</pyd_amount>
<pin_cc_auth>935PNI</pin_cc_auth>
<pin_other_ref_number>V18A0AA26D55</pin_other_ref_number>
</PaymentObject>
<PaymentObject>
<pay_key>f4f0a480-aaf5-4a61-8250-ff8510af2024</pay_key>
<pay_cst_key>382454e1-97fd-493c-b12b-e504a926da18</pay_cst_key>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<ivd_key>8909ddb5-d41f-4146-b148-809ec9168c51</ivd_key>
<ivd_closed_flag>1</ivd_closed_flag>
<pay_trx_date>10/9/2006 12:00:00 AM</pay_trx_date>
<pyd_type>payment</pyd_type>
<pay_code>32485</pay_code>
<pyd_amount>1.8</pyd_amount>
<pin_cc_auth>935PNI</pin_cc_auth>
<pin_other_ref_number>V18A0AA26D55</pin_other_ref_number>
</PaymentObject>
<PaymentObject>
<pay_key>f4f0a480-aaf5-4a61-8250-ff8510af2024</pay_key>
<pay_cst_key>382454e1-97fd-493c-b12b-e504a926da18</pay_cst_key>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<ivd_key>d458dd02-c6cc-4184-b654-949352bd3e93</ivd_key>
<ivd_closed_flag>1</ivd_closed_flag>
<pay_trx_date>10/9/2006 12:00:00 AM</pay_trx_date>
<pyd_type>payment</pyd_type>
<pay_code>32485</pay_code>
<pyd_amount>0.11</pyd_amount>
<pin_cc_auth>935PNI</pin_cc_auth>
<pin_other_ref_number>V18A0AA26D55</pin_other_ref_number>
</PaymentObject>
<PaymentObject>
<pay_key>f4f0a480-aaf5-4a61-8250-ff8510af2024</pay_key>
<pay_cst_key>382454e1-97fd-493c-b12b-e504a926da18</pay_cst_key>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<ivd_key>0fce472e-04d1-4759-8524-9bd2c8156576</ivd_key>
<ivd_closed_flag>1</ivd_closed_flag>
<pay_trx_date>10/9/2006 12:00:00 AM</pay_trx_date>
<pyd_type>payment</pyd_type>
<pay_code>32485</pay_code>
<pyd_amount>1.14</pyd_amount>
<pin_cc_auth>935PNI</pin_cc_auth>
<pin_other_ref_number>V18A0AA26D55</pin_other_ref_number>
</PaymentObject>
<PaymentObject>
<pay_key>f4f0a480-aaf5-4a61-8250-ff8510af2024</pay_key>
<pay_cst_key>382454e1-97fd-493c-b12b-e504a926da18</pay_cst_key>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<ivd_key>bb2d751f-0322-4b51-9b2c-b28d355c1577</ivd_key>
<ivd_closed_flag>1</ivd_closed_flag>
<pay_trx_date>10/9/2006 12:00:00 AM</pay_trx_date>
<pyd_type>payment</pyd_type>
<pay_code>32485</pay_code>
<pyd_amount>1.14</pyd_amount>
<pin_cc_auth>935PNI</pin_cc_auth>
<pin_other_ref_number>V18A0AA26D55</pin_other_ref_number>
</PaymentObject>
<PaymentObject>
<pay_key>f4f0a480-aaf5-4a61-8250-ff8510af2024</pay_key>
<pay_cst_key>382454e1-97fd-493c-b12b-e504a926da18</pay_cst_key>
<inv_key>b7241397-71f6-4806-9166-2c8629b64112</inv_key>
<ivd_key>74289c18-66e3-4924-a0b6-ccdcc81aad67</ivd_key>
<ivd_closed_flag>1</ivd_closed_flag>
<pay_trx_date>10/9/2006 12:00:00 AM</pay_trx_date>
<pyd_type>payment</pyd_type>
<pay_code>32485</pay_code>
<pyd_amount>57</pyd_amount>
<pin_cc_auth>935PNI</pin_cc_auth>
<pin_other_ref_number>V18A0AA26D55</pin_other_ref_number>
</PaymentObject>
</PaymentObjects>
</CreatePaymentResult>
</CreatePaymentResponse>
</soap:Body>
</soap:Envelope>

ACH

If you're making an ACH payment, be sure to set these properties:

pin_city
pin_state
pin_eft_account_type
pin_name_on_check
pin_eft_routing_number
pin_eft_account_number

The <pin_eft_account_number> element must be encrypted in the same way that the credit card number is encrypted as described in Credit Card Encryption.