Merchant Web Services API Customer Information Manager (CIM) SOAP Guide

8/10/2019 Merchant Web Services API Customer Information Manager (CIM) SOAP Guide

1/91


2/91

2

Authorize.Net LLC (Authorize.Net) has made efforts to ensure the accuracy and completeness of theinformation in this document. However, Authorize.Net disclaims all representations, warranties and conditions,whether express or implied, arising by statute, operation of law, usage of trade, course of dealing or otherwise,with respect to the information contained herein. Authorize.Net assumes no liability to any party for any loss ordamage, whether direct, indirect, incidental, consequential, special or exemplary, with respect to (a) theinformation; and/or (b) the evaluation, application or use of any product or service described herein.

Authorize.Net disclaims any and all representation that its products or services do not infringe upon any existingor future intellectual property rights. Authorize.Net owns and retains all right, title and interest in and to the

Authorize.Net intellectual property, including without limitation, its patents, marks, copyrights and technologyassociated with the Authorize.Net services. No title or ownership of any of the foregoing is granted or otherwisetransferred hereunder. Authorize.Net reserves the right to make changes to any information herein withoutfurther notice.

Authorize.Net Trademarks Advanced Fraud Detection Suite

Authorize.Net

Authorize.Net Your Gateway to IP Transactions

Authorize.Net Verified Merchant Seal

Automated Recurring Billing

eCheck.Net

FraudScreen.Net


3/91

Customer Information Manager Guide | June 2014 3

C O N T E N T S

Contents

Revision History 6

Chapter 1 Developer Introduction 7 Audience For This Guide 7Integration Methods 7

Standard API 8

Hosted Form 8

Minimum Requirements 8

Payment Processors 9North American Payment Processors 9

Accepted Card Types 9 Accepted Currencies 9

European Payment Processors 10 Asia-Pacific Processors 11

Developer Support 11

Software Development Kits 11

Chapter 2 Executing an API Call 12Web Service Locations 12

CIM Functions 13The validationMode Parameter 14

Authentication 15Input Parameters for CreateCustomerProfile 16Input Parameters for CreateCustomerPaymentProfile 22

Input Parameters for CreateCustomerShippingAddress 25Input Parameters for CreateCustomerProfileTransaction 26

For Authorization Only transactions 26For Authorization and Capture Transactions 31For Capture Only Transactions 36For Prior Authorization and Capture Transactions 40For Refund Transactions 44For a Void Transaction 49
http://-/?-http://-/?-


4/91


Contents

Input Parameters for DeleteCustomerProfile 50Input Parameters for DeleteCustomerPaymentProfile 50Input Parameters for DeleteCustomerShippingAddress 51Input Parameters for GetCustomerProfileIds 51

Input Parameters for GetCustomerProfile 52Input Parameters for GetCustomerPaymentProfile 53Input Parameters for GetCustomerShippingAddress 53Input Parameters for GetHostedProfilePage 54Input Parameters for UpdateCustomerProfile 55Input Parameters for UpdateCustomerPaymentProfile 55Input Parameters for UpdateCustomerShippingAddress 60Input Elements for UpdateSplitTenderGroup 62Input Parameters for ValidateCustomerPaymentProfile 62

Chapter 3 Responses 64CIM Responses 65

Output for CreateCustomerProfileResponse 65Output for CreateCustomerPaymentProfileResponse 67Output for CreateCustomerShippingAddressResponse 67Output for CreateCustomerProfileTransactionResponse 68Output for DeleteCustomerProfileResponse 69Output for DeleteCustomerPaymentProfileResponse 69Output for DeleteCustomerShippingAddressResponse 69Output for GetCustomerProfileIdsResponse 70Output for GetCustomerProfileResponse 70Output for GetCustomerPaymentProfileResponse 73Output for GetCustomerShippingAddressResponse 76Output for GetHostedProfilePage 78Output for UpdateCustomerProfileResponse 78Output for UpdateCustomerPaymentProfileResponse 78Output for UpdateCustomerShippingAddressResponse 79Output for UpdateSplitTenderGroup 79Output for ValidateCustomerPaymentProfileResponse 80Duplicate Profile Verification 80

Chapter 4 Using a Hosted Form 82Identifying the Customer 82

Retrieving a Token 82

Presenting the Hosted Form 83Form Action URLs 83

Conditional fields 83

Displaying the Form 83


5/91


Contents

Redirect 84iFrame 85

Guidelines for Parameter Settings 85

Response Codes 88

Index 90


6/91


R E V I S I O N S

Revision History

This table lists the changes made in the last six releases of this document:

Publ ish Date Update

June 2014 This version contains only formatting updates and does not include anycontent updates.

February 2014 Updated the section "Developer Support."

Updated the section "Payment Processors."

December 2013 Updated Chapter 4 to clarify the process of generating the hosted form. See"Using a Hosted Form," page 82 .

October 2013 Updated the table of "Payment Processors" .

April 2013 Updated the table of "Payment Processors" .

February 2013 Updated the table of "Payment Processors" .


7/91


C H A P T E R

1Developer Introduction

This guide describes the Web development required to create and manage customerprofile information for the purpose of submitting transactions to the Authorize.Net PaymentGateway directly from a Web site or other application using Simple Object AccessProtocol (SOAP).

SOAP provides a standards-based mechanism to access Web services from a wide rangeof platforms. Typically, you access Web services using a SOAP client on yourprogramming environment. The SOAP client typically generates the native objects andinterfaces based on a Web Services Description Language (WSDL) that is published by

Authorize.Net. The client application initializes the local object and invokes the method asif it is calling a local procedure. The SOAP client generates and parses the underlyingextensible markup language (XML) documents that form the basis of the SOAP protocol.

The Authorize.Net Customer Information Manager (CIM) Application ProgrammingInterface (API) provides a mechanism for developers and value-added resellers (VARs) tocreate, delete, retrieve, and update customer profile information, including payment andaddress information, by directly integrating client software and the Authorize.Net PaymentGateway.

Please refer to specific SOAP client documentation for details on how to use SOAP-basedWeb services.

Audience For This GuideThis guide is intended for developers who are responsible for maintaining a merchantswebsite and integrating it with the Authorize.Net Payment Gateway.

Integration MethodsThe two methods for integrating payments, Standard API and Hosted API, canaccommodate a range of business needs and coding abilities.


8/91


Chapter 1 Developer Introduction

Standard APIYou can use the API to submit transaction information to Authorize.Net when yourcustomers enter data on your website. When the customer enters the data, your website

calls the API using either XML or SOAP.

The choice of XML or SOAP depends on the programming language you use. For PHPand Ruby, XML is recommended. For C# and other .NET languages, SOAP isrecommended. With Java, either will work.

For information regarding requirements for using the API, see "Minimum Requirements" below.

Hosted FormFor a more secure exchange of information, a hosted form enables you to establish ahosted connection on Authorize.Net secure servers. If the merchant needs to transmitsensitive cardholder information (for example, a customer needs to change credit cardinformation or add a new payment method), you can use the hosted form option. With thehosted CIM option, credit card data never flows through your website. You can implementthe hosted option using either XML or SOAP.

You must still use the standard API (either SOAP or XML) for some operations, such ascreating a transaction. The hosted page only provides functionality for creating, updating,

and deleting payment profiles and shipping addresses.

For more information, refer to "Using a Hosted Form," page 82 .

Minimum RequirementsBefore you begin integrating an Authorize.Net Payment Gateway account, check with themerchant to make sure that the following minimum requirements have already been met.

The merchant must have a merchant bank account that allows Internet transactions.The merchant must have an active Authorize.Net Card Not Present PaymentGateway account.

The merchant must have signed up for the CIM service.

The merchant must store account authentication data securely (for example, API loginID, transaction key).


9/91



The merchants website must use HTTPS.

The merchants website must support secure user registration for returning users.

Payment ProcessorsThe currencies that a merchant can accept through Authorize.Net are determined by theirpayment processor.

North American Payment Processors

Accepted Card Types All North American payment processors supported by Authorize.Net accept the followingcard types:

American ExpressDiners Club

Discover

JCB

Mastercard

Visa

Accepted Currenc ies

Note

Merchants should avoid storing any type of sensitive cardholderinformation. However, if a merchant or third party must store sensitivecustomer business or payment information, they must comply with industrystandard storage requirements. See the Developer Security Best PracticesWhite Paper at http://www.authorize.net/files/developerbestpractices.pdf for guidelines.

Table 1 North American Payment Processors and Accepted CurrenciesPayment Processor Accepted Currencies

Chase Paymentech Tampa Processing Platform United States Dollar (USD)

Canadian Dollar (CAD)

Elavon United States Dollar (USD)

Canadian Dollar (CAD)
http://www.authorize.net/files/developerbestpractices.pdfhttp://www.authorize.net/files/developerbestpractices.pdf


10/91



European Payment ProcessorsThe following European payment processors are supported by Authorize.Net for Card Not

Present (CNP) transactions.

First Data Merchant Services (FDMS) Omaha,Nashville, and EFSNet Processing Platforms

United States Dollar (USD)

Global Payments United States Dollar (USD)Canadian Dollar (CAD)

Heartland Payment Systems United States Dollar (USD)

TSYS Acquiring Solutions United States Dollar (USD)

WorldPay Atlanta Processing Platform United States Dollar (USD)

Table 1 North American Payment Processors and Accepted Currencies

Payment Processor Accepted Currencies

Table 2 European Payment Processors, Accepted Card Types, and Accepted Currencies

Payment Processor Accepted Card Types Accepted Currencies

AIB Merchant Services Mastercard

Visa

British Pounds (GBP)

Euro (EUR)


Barclaycard JCB

Mastercard

Visa


Euro (EUR)

First Data Merchant Solutions (MSIP platform) Mastercard

Visa


HSBC Merchant Services Mastercard

Visa


Euro (EUR)

Lloyds Bank Cardnet Mastercard

Visa


Streamline JCB

Mastercard

Visa


Euro (EUR)



11/91



Asia-Pacific ProcessorsThe following Asia-Pacific payment processors are supported by Authorize.Net for CardNot Present (CNP) transactions.

Developer SupportResources are available to help you successfully integrate a merchant web site or otherapplication to the Authorize.Net payment gateway.

The Developer Center provides sandbox accounts, sample code, FAQs, andtroubleshooting tools. http://developer.authorize.net

Developer Training Videos: http://developer.authorize.net/training .

The Developer Community provides answers to questions from other Authorize.Netdevelopers.

http://community.developer.authorize.netDeveloper Support: http://developer.authorize.net/support .

If you have suggestions for improving or correcting this guide, send email [email protected] .

Software Development Kits Authorize.Net offers software development kits (SDKs) that present an alternate object-oriented model in several popular languages. Use the SDK to program the core paymentactivities (such as error handling and parsing, network communication, and dataencoding) that occur behind the scenes.

The SDK provides utility methods to help developers build payment flows for each of theintegration methods. You can download the SDKs at http://developer.authorize.net/downloads/ .

Table 3 Asia-Pacific Payment Processor, Accepted Card Types, and Accepted Currencies

Payment Processor Accepted Card Types Accepted Currencies

FDI Australia Mastercard

Visa

Australian Dollar (AUD)

New Zealand Dollar (NZD)


Westpac Mastercard

Visa

Australian Dollar (AUD)
http://developer.authorize.net/http://developer.authorize.net/http://developer.authorize.net/traininghttp://developer.authorize.net/training.http://community.developer.authorize.net/http://developer.authorize.net/supporthttp://developer.authorize.net/downloadshttp://developer.authorize.net/downloadshttp://developer.authorize.net/downloadshttp://developer.authorize.net/downloadshttp://developer.authorize.net/supporthttp://community.developer.authorize.net/http://developer.authorize.net/training.http://developer.authorize.net/training.http://developer.authorize.net/traininghttp://developer.authorize.net/http://developer.authorize.net/


12/91


C H A P T E R

2Executing an API Call

The following sections describe the minimum requirements for executing an API call formanaging customer profiles using SOAP.

You can develop a request script in one of two ways:

Develop a custom script yourself using the API field information provided in thisdocument

Use Authorize.Net sample code available for free from our Developer Center at http://developer.authorize.net/samplecode .

Web Service LocationsThe following table shows where to find the API.

Note

If you choose to use Authorize.Net sample code, please be aware that in orderto achieve a successful implementation, you must modify the code withdeveloper test account or the merchants specific payment gateway accountinformation.

Item Location

Web Service URL in Production https://api.authorize.net/soap/v1/Service.asmx

Web Service URL in DeveloperTest

https://apitest.authorize.net/soap/v1/Service.asmx

WSDL https://api.authorize.net/soap/v1/Service.asmx?WSDL

Note

The developer test URL requires the use of a developer test payment gatewayaccount. You can request a test account from our Developer Center athttp://developer.authorize.net/testaccount . Developer test accounts cannot beused to test your implementation against the production URL.
http://developer.authorize.net/samplecodehttp://developer.authorize.net/samplecodehttp://developer.authorize.net/testaccounthttp://developer.authorize.net/samplecodehttp://developer.authorize.net/samplecodehttp://developer.authorize.net/testaccount


13/91


14/91


Chapter 2 Executing an API Call

UpdateSplitTenderGroupUpdate the status of a split tender group (a group oftransactions each of which pays for part of one order).

ValidateCustomerPaymentProfileVerify an existing customer payment profile bygenerating a test transaction.

The following sections provide information about the input parameters required forexecuting the functions listed above. All parameters are case sensitive and must besubmitted in the order listed here. Parameters are required unless otherwise indicated.Optional parameters should not be submitted unless they contain valid values.

The validationMode Parameter The validationMode parameter enables you to generate a test transaction at the time youcreate or update a customer profile. The functions CreateCustomerProfile,CreateCustomerPaymentProfile, UpdateCustomerPaymentProfile, andValidateCustomerPaymentProfile all include a validationMode parameter, which can haveone of the following values:

liveModeThis value is the default setting.

liveMode generates a transaction to the processor in the amount of $0.01 or $0.00. Ifsuccessful, the transaction is immediately voided. Visa authorization transactions arechanging from $0.01 to $0.00 for all processors. All other credit card types use $0.01.Standard gateway and merchant account fees may apply to the authorization

transactions.For Visa transactions using $0.00, the billTo address and billTo zip fields are required.

testModePerforms field validation only. All fields are validated. However, fields withunrestricted field definitions (such as telephone number) do not generate errors.

If you select testMode, a $1.00 test transaction is submitted using the Luhn MOD 10algorithm to verify that the credit card number is in a valid format. This test transactiondoes not appear on the customer's credit card statement, but it will generate and senda transaction receipt email to the merchant.

Note

Parameters required for individual API calls are in addition to the authenticationparameters required for all API calls.

Note

For .NET programmers : When a parameter is optional, and if you useserialization, then the .NET language you are using automatically createsBoolean properties that indicate whether or not non-nullable parameters arespecified. For example, if there is a parameter named validationMode that is anEnumeration type, a parameter called validationModeSpecified isautomatically created. By default, these properties are set to false. If a requestpasses a value for an optional parameter, be sure to set these properties to trueso that the value is not ignored.


15/91



noneWhen this value is submitted, no additional validation is performed.

When you call the CreateCustomerProfile function, you must use a value of none if therequest does not include any payment profile information.

When you call the ValidateCustomerPaymentProfile function, you must use either

testMode or liveMode.

If a validation transaction is unsuccessful, the profile is not created, and the merchantreceives an error.

Authentication All Web services calls must be authenticated to ensure that they originate from authorizedsources. The merchant Web services API authenticates calls with the API Login ID andTransaction Key.

Example Authentic ation with the Login ID and Transaction Key

The authentication information with the merchants Login ID and Transaction Key is sent inthe SOAP:Body tag, as shown below:

API Logi n I D her e

Note

For information about the hostedProfileValidationMode parameter, see"Guidelines for Parameter Settings," page 85 .

Table 4 Merchant Authentication

Parameter Description

merchantAuthentication Value : Contains merchant unique information for purposes ofauthentication

Type : MerchantAuthenticationType

name Value : The valid API Login ID for the developer test or merchantaccount

Format : 20 characters

Notes: Submit the API Login ID used to submit transactions

transactionKey Value : The valid Transaction Key for the developer test ormerchant account


Notes: Submit the Transaction Key obtained from the MerchantInterface


16/91



Tr ansact i on Key her eAddi t i onal r equi r ed paramet ers her e

Input Parameters for CreateCustomerProfileThis function is used to create a new customer profile including any customer paymentprofiles and customer shipping addresses.

The following table lists the input parameters for executing an API call to theCreateCustomerProfile function.

Note

The sample code included in this document uses generic field values. Whenusing or testing sample code, be sure to enter valid field values. Additionalsample code is available for download from the Authorize.Net DeveloperCenter at http://developer.authorize.net/samplecode .

Table 5 Input Parameters for CreateCustomerProfile

Field Description

profile Value : Contains information for the customer profile

Type: CustomerProfileType

Notes : At least one of the following fields must be submitted under profile:

merchantCustomerId, description, or email.merchantCustomerId Value : Merchant assigned ID for the customer

Conditional

Format : Up to 20 characters

Notes : Required only if no values for both description and email are submitted.

description Value : Description of the customer or customer profile

Conditional


Notes : Required only if no values for both merchantCustomerId and email aresubmitted.

email Value : Email address associated with the customer profile

Conditional


Notes : Required if no values for both description and merchantCustomerId aresubmitted.

Required only when using a European payment processor.
http://developer.authorize.net/samplecodehttp://developer.authorize.net/samplecode


17/91


18/91



zip Value : The ZIP code of the customers address

Optional

Format : Up to 20 characters (no symbols)

Notes : Required only when using a European payment processor.

country Value : The country of the customers address

Optional


Notes : Required only when using a European payment processor.

phoneNumber Value : The phone number associated with the customer profile

Optional

Format : Up to 25 digits (no letters) For example, (123)123-1234

faxNumber Value : The fax number associated with the customer profile

Optional


payment Value : Contains payment profile information for the customer profile

Type : PaymentSimpleType

Notes : Can contain CreditCardSimpleType or BankAccountType.

creditCard Value : Contains credit card payment information for the payment profile

Type : CreditCardSimpleType

Notes : This parameter and its children are only required when the payment

profile is credit card. cardNumber Value : The customers credit card number

Format : 13 to 16 digits

expirationDate Value : The expiration date for the customers credit card

Format : YYYY-MM

Notes : For .Net users, the classSystem.Runtime.Remoting.Metadata.W3cXsd2001.SoapYearMonth can beused to manage gYearMonth types.

Table 5 Input Parameters for CreateCustomerProfile (Continued)

Field Description


19/91



cardCode Value : The three- or four-digit number on the back of a credit card (on the frontfor American Express)

OptionalFormat : Numeric

Notes : This field is required if the merchant would like to use the Card CodeVerification (CCV) security feature. For more information, see the MerchantIntegration Guide at http://www.authorize.net/support/merchant/ .

cardCode is used only for validation and is not stored in the customer profile.Use it only when submitting validationMode with a value of testMode orliveMode.

bankAccount Value : Contains bank account payment information for the payment profile

Type : BankAccountType

Notes : This parameter and its children are required only when the paymentprofile is bank account.

accountType Value : The type of bank account for the payment profile

Optional

type : BankAccountTypeEnum

Format : checking , savings, or businessChecking

routingNumber Value : The routing number of the customers bank

Format : 9 digits

accountNumber Value : The customers bank account number


nameOnAccount Value : The customers full name as listed on the bank account


echeckType Value : The type of electronic check transaction

Optional

Type : EcheckTypeEnum

Format : CCD, PPD, TEL, or WEB

Notes : Currently, the CIM API does not support ARC or BOC transaction types.

bankName Value : The name of the bank associated with the bank account number

Optional


shipToList Value : Contains shipping address information for the customer profile

Type : CustomerAddressType

firstName Value : The customers first name

Optional



Field Description
http://www.authorize.net/support/merchant/http://www.authorize.net/support/merchant/


20/91



lastName Value : The customers last name

Optional


company Value : The name of the company associated with the customer, if applicable

Optional


address Value : The customers shipping address

Optional


city Value : The city of the customers shipping address

Optional


state Value : The state of the customers shipping address

Optional


zip Value : The ZIP code of the customers shipping address

Optional


country Value : The country of the customers shipping address

Optional


phoneNumber Value : The phone number associated with the customer profile

Optional

Format : Up to 25 digits (no letters)

For example, (123)123-1234

faxNumber Value : The fax number associated with the customer profile

Optional

Format : Up to 25 digits (no letters)

For example, (123)123-1234

validationMode Value : Indicates the processing mode for the request

Optional

Format : none, testMode, or liveMode

Notes : For more information on use and restrictions of validationMode, see"The validationMode Parameter," page 14 .


Field Description


21/91


22/91


23/91


24/91



For information about output parameters for this function, see the section of this document

titled "Output for CreateCustomerPaymentProfileResponse."

bankAccount Value : Contains bank account payment information for the customer profile


Notes : This parameter and its children arerequired only when the paymentprofile is bank account.


Optional

Type : BankAccountTypeEnum

Format : checking, savings, or businessChecking


Format : 9 digits


Format : 5 to 17 digitsnameOnAccount Value : The customers full name as listed on the bank account



Optional


Format : CCD, PPD, TEL, or WEB

Notes : Currently, the CIM API does not support ARC or BOC transactiontypes.


Optional



Type : ValidationModeEnum

Format : none, testMode, or liveMode

Notes : For more information on use and restrictions of validationMode,see "The validationMode Parameter," page 14 .

Table 6 Input Parameters for CreateCustomerPaymentProfile (Continued)

Field Description


25/91



Input Parameters forCreateCustomerShippingAddressThis function is used to create a new customer shipping address for an existing customerprofile.

The following table lists the input parameters for executing an API call to theCreateCustomerShippingAddress function.

Table 7 Input Parameters for CreateCustomerShippingAddress

Field Description

customerProfileId Value : Payment gateway assigned ID associated with the customer profile

Format : Numeric

address Value : Contains shipping address information for the customer profile

Type : CustomerAddressType


Optional


lastName Value : The customers last name

Optional


company Value : The name of the company associated with the customer, ifapplicable

Optional

Format : Up to 50 characters (no symbols)address Value : The customers shipping address

Optional


city Value : The city of the customers shipping address

Optional


state Value : The state of the customers shipping address

Optional

Format : Up to 40 characters (no symbols)zip Value : The ZIP code of the customers shipping address

Optional



26/91



For information about output parameters for this function, see the section of this documenttitled "Output for CreateCustomerShippingAddressResponse."

Input Parameters forCreateCustomerProfileTransactionThis function is used to create a payment transaction from an existing customer profile.You can submit one of six transaction types: Authorization Only, Authorization andCapture, Capture Only, Prior Authorization and Capture, Refund, and Void. For moreinformation on these transaction types, see the Merchant Integration Guide at http://

www.authorize.net/support/merchant/ .

For Authorization Only transactionsThe following table lists the input parameters for executing an API call to theCreateCustomerProfileTransaction function for an Authorization Only transaction.

country Value : The country of the customers shipping address

Optional


phoneNumber Value : The phone number associated with the customers shippingaddress

Optional


faxNumber Value : The fax number associated with the customers shipping address

Optional


Table 7 Input Parameters for CreateCustomerShippingAddress (Continued)

Field Description

Note

The only transaction types that generate a customer receipt email are Authorization Only, Authorization and Capture, and Refund.

Table 8 Input Parameters for CreateCustomerProfileTransaction

Field Description

transaction Value : Contains transactioninformation

Type : ProfileTransactionType
http://www.authorize.net/support/merchant/http://www.authorize.net/support/merchant/http://www.authorize.net/support/merchant/http://www.authorize.net/support/merchant/


27/91



profileTransAuthOnly Value : The transaction type that is being requested

Type : ProfileTransAuthOnlyType

Notes : Only one transaction type is allowed per request.

amount Value : The total amount of the transaction

Format : Up to 4 digits after the decimal point (no dollarsymbol)

For example, 12.99 or 12.9999

Notes : This amount should include all other amountssuch as tax amount, shipping amount, etc.

tax Value : Contains tax information for the transaction

Optional

Type : ExtendedAmountType

amount Value : The tax amount for the transaction

Optional



Notes : This amount must be included in the total amountfor the transaction.

name Value : The name of the tax for the transaction

Optional

Format : Up to 31 characters description Value : The tax description for the transaction

Optional


shipping Value : Contains shipping information for the transaction

Optional


amount Value : The shipping amount for the transaction

Optional




Table 8 Input Parameters for CreateCustomerProfileTransaction (Continued)

Field Description


28/91



name Value : The name of the shipping for the transaction

Optional


description Value : The shipping description for the transaction

Optional


duty Value : Contains duty information for the transaction

Optional


amount Value : The duty amount for the transaction

Optional




name Value : The name of the duty for the transaction

Optional

vUp to 31 characters

description Value : The duty description for the transaction

Optional


lineItems Value : Contains line item details about the order

Optional

Type : LineItemType

Notes : Up to 30 distinct instances of this parameter andits children can be included per transaction to describeitems included in the order.

itemId Value : The ID assigned to the item

Optional

Format : Up to 31 characters name Value : A short description of an item

Optional



Field Description


29/91



description Value : A detailed description of an item

Optional


quantity Value : The quantity of an item

Optional

Format : Up to 4 digits (up to two decimal places)

unitPrice Value : Cost of an item per unit excluding tax, freight, andduty

Optional

Format : Up to 4 digits with a decimal point (no dollarsymbol)

For example, 4.95

taxable Value : Indicates whether the item is subject to tax

Optional

Format : true or false

customerProfileId Value : Payment gateway assigned ID associated withthe customer profile

Format : Numeric

customerPaymentProfileId Value : Payment gateway assigned ID associated withthe customer payment profile

Format : Numeric

customerShippingAddressId Value : Payment gateway assigned ID associated withthe customer shipping address

Optional

Format : Numeric

Notes : If customerShippingAddressId is not passed,shipping information will not be included with thetransaction.

order Value : Contains information about the order

Optional

Type : OrderExType

invoiceNumber Value : The merchant assigned invoice number for thetransaction

Optional



Field Description


30/91



For information about output parameters for this function, see the section of this documenttitled "Input Parameters for CreateCustomerProfileTransaction."

description Value : The transaction description

Optional


purchaseOrderNumber Value : The merchant assigned purchase order number

Optional


taxExempt Value : The tax exempt status

Optional


recurringBilling Value : The recurring billing status

Optional


cardCode Value : The customers card code (the three- or four-digitnumber on the back or front of a credit card)

Conditional.


Notes : This field is required if the merchant would like touse the Card Code Verification (CCV) security feature.For more information, see the Merchant IntegrationGuide at http://www.authorize.net/support/merchant/

splitTenderId Value : Payment gateway-assigned number associated

with the order.Conditional

Format : Up to 6 digits

Notes : This field is required for second and subsequenttransactions related to a partial authorizaqtiontransaction.

extraOptions Value : Information in name/value pair format that doesnot exist within CIM, such as customer IP address, etc.

Optional

Format : String

Notes : For a complete list of the transaction variablenames available, review the AIM Implementation Guide located at http://www.authorize.net/support/AIM_guide.pdf .


Field Description
http://www.authorize.net/support/merchant/http://www.authorize.net/support/AIM_guide.pdfhttp://www.authorize.net/support/AIM_guide.pdfhttp://www.authorize.net/support/AIM_guide.pdfhttp://www.authorize.net/support/AIM_guide.pdfhttp://www.authorize.net/support/merchant/


31/91



For Authorization and Capture TransactionsThe following table lists the input parameters for executing an API call to theCreateCustomerProfileTransaction function for an Authorization and Capture transaction.


Field Description

transaction Value : Contains transaction information Type :ProfileTransactionType

profileTransAuthCapture Value : The transaction type that is beingrequested Type : ProfileTransAuthCaptureType

Notes : Only one transaction type is allowed perrequest.


Format : Up to 4 digits after the decimal point (nodollar symbol)




Optional Type : ExtendedAmountType


Optional


For example, 12.99 or 12.9999Notes : This amount must be included in the totalamount for the transaction.


Optional


description Value : The tax description for the transaction

Optional


shipping Value : Contains shipping information for thetransaction

Optional



32/91




Optional



Notes : This amount must be included in the totalamount for the transaction.


Optional



Optional



Optional



Optional





Optional



Optional



OptionalType : LineItemType

Notes : Up to 30 distinct instances of this parameterand its children can be included per transaction todescribe items included in the order.


Field Description


33/91




Optional


name Value : A short description of an item

Optional



Optional



Optional


unitPrice Value : Cost of an item per unit excluding tax, freight,and duty

Optional

Format : Up to 4 digits with a decimal point (no dollarsymbol)

For example, 4.95


Optional

Format : TRUE or FALSE

customerProfileId Value : Payment gateway-assigned ID associatedwith the customer profile

Format : Numeric

customerPaymentProfileId Value : Payment gateway-assigned ID associatedwith the customer payment profile

Format : Numeric

customerShippingAddressId Value : Payment gateway-assigned ID associatedwith the customer shipping address

Optional

Format : NumericNotes : If customerShippingAddressId is not passed,shipping information will not be included with thetransaction.


Optional Type : OrderExType


Field Description


34/91



invoiceNumber Value : The merchant-assigned invoice number forthe transaction

OptionalFormat : Up to 20 characters (no symbols)


Optional


purchaseOrderNumber Value : The merchant-assigned purchase ordernumber

Optional



Optional



Optional


cardCode The customers card code (the three- or four-digitnumber on the back or front of a credit card)

Conditional


Notes : This field is required if the merchant would liketo use the Card Code Verification (CCV) securityfeature. For more information, see the MerchantIntegration Guide at http://www.authorize.net/support/merchant/default.htm.

splitTenderId Value: The payment gateway-assigned numberassociated with the order.

Conditional


Notes : This field is required for second andsubsequent transactions related to a partialauthorization transaction.


Field Description
http://www.authorize.net/support/merchant/http://www.authorize.net/support/merchant/http://www.authorize.net/support/merchant/http://www.authorize.net/support/merchant/


35/91



For information about output parameters for this function, see the section of this documenttitled "Output for CreateCustomerProfileTransactionResponse."

extraOptions Information in name/value pair format that does notexist within CIM, such as customer IP address, etc.

OptionalFormat : String

Notes : For a complete list of the transaction variablenames available, review the AIM ImplementationGuide located at http://www.authorize.net/support/

AIM_guide.pdf .


Field Description
http://www.authorize.net/support/AIM_guide.pdfhttp://www.authorize.net/support/AIM_guide.pdfhttp://www.authorize.net/support/AIM_guide.pdfhttp://www.authorize.net/support/AIM_guide.pdf


36/91



For Capture Only TransactionsThe following table lists the input parameters for executing an API call to theCreateCustomerProfileTransaction function for a Capture Only transaction.


Field Description

transaction Value : Contains transaction information


profileTransCaptureOnly Value : The transaction type that is being requested

Type : ProfileTransCaptureOnlyType

Notes : Only one transaction type is allowed perrequest.


Format : Up to 4 digits after the decimal point (no dollar

symbol)For example, 12.99 or 12.9999



Optional



Optional





Optional



Optional

Format : Up to 255 charactersshipping Value : Contains shipping information for the transaction

Optional Type : ExtendedAmountType


37/91




Optional





Optional



Optional



Optional



Optional





Optional



Optional



Optional Type : LineItemTypeNotes : Up to 30 distinct instances of this parameter andits children can be included per transaction to describeitems included in the order.


Optional



Field Description


38/91




Optional



Optional



Optional


unitPrice Value : Cost of an item per unit excluding tax, freight,and duty

OptionalFormat : Up to 4 digits with a decimal point (no dollarsymbol)

For example, 4.95


Optional



Format : Numeric

customerPaymentProfileId Value : Payment gateway assigned ID associated withthe customer payment profile

Format : Numeric


Optional

Format : Numeric

Notes : If customerShippingAddressId is not passed,shipping information will not be included with thetransaction.


Optional

Type : OrderExType


Field Description


39/91




OptionalFormat : Up to 20 characters (no symbols)


Optional



Optional



OptionalFormat : TRUE or FALSE


Optional


cardCode Value : The customers card code (the three- or four-digitnumber on the back or front of a credit card)

Conditional


Notes : This field is required if the merchant would like touse the Card Code Verification (CCV) security feature.For more information, see the Merchant IntegrationGuide at http://www.authorize.net/support/Merchant/default.htm .

splitTenderId Value: Payment gateway-assigned number associatedwith the order.

Conditional


Notes : This field is only required for second andsubsequent transactions related to a partialauthorizaqtion transaction.

approvalCode Value : The authorization code of an original transactionrequired for a Capture Only

Conditional


Notes : This field is onlyrequired for the Capture Onlytransaction type.


Field Description
http://www.authorize.net/support/Merchant/default.htmhttp://www.authorize.net/support/Merchant/default.htmhttp://www.authorize.net/support/Merchant/default.htmhttp://www.authorize.net/support/Merchant/default.htm


40/91


41/91




Optional


for example, 12.99 or 12.9999



Optional



Optional


shipping Value : Contains shipping information for the transaction

Optional


Notes : Shipping information from the originalauthorization transaction will be used if this field is notsubmitted.


Optional





Optional



Optional



Optional


Notes : Duty information from the original authorizationtransaction will be used if this field is not submitted.

Table 11 Input Parameters for CreateCustomerProfil eTransaction (Continued)

Field Description


42/91




Optional





Optional



Optional



Optional

Type : LineItemType

Notes : Line item information from the originalauthorization transaction will be used if this field is notsubmitted.

Up to 30 distinct instances of this parameter and itschildren can be included per transaction to describeitems included in the order.


Optional



Optional



Optional



Optional



Field Description


43/91



For information about output parameters for this function, see the section of this documenttitled "Output for CreateCustomerProfileTransactionResponse."

unitPrice Value : Cost of an item per unit excluding tax, freight, andduty

OptionalFormat : Up to 4 digits with a decimal point (no dollarsymbol)

For example, 4.95


Optional


customerProfileId Value : Payment gateway-assigned ID associated withthe customer profile

Format : Numeric

Notes : If a value is submitted for this field, it must be thesame ID used for the original authorization transaction.

customerPaymentProfileId Value : Payment gateway-assigned ID associated withthe customer payment profile

Format : Numeric


customerShippingAddressId Value : Payment gateway-assigned ID associated withthe customer shipping address

Optional

Format : Numeric


transId Value : The payment gateway-assigned transaction ID ofthe original transaction

Format : Numeric


Optional

Format : String

Notes : For a complete list of the transaction variablenames available, review the AIM Implementation Guidelocated at http://www.authorize.net/support/AIM_guide.pdf.


Field Description


44/91


45/91



tax Value : Contains tax information for the refund

Optional


amount Value : The tax amount to be refunded

Optional





Optional



Optional


shipping Value : Contains shipping information for the refund

Optional


amount Value : The shipping amount to be refunded

Optional





Optional



OptionalFormat : Up to 255 characters

duty Value : Contains duty information for the refund

Optional



Field Description


46/91



amount Value : The duty amount to be refunded

Optional





Optional



Optional

Up to 255 characters Format :

lineItems Value : Contains line item details about the refund

Optional

Type : LineItemType

Notes : Up to 30 distinct instances of this parameter andits children can be included per transaction to describeitems included in the order.


Optional

Format : Up to 31 characters name Value : A short description of an item

Optional



Optional



Optional

Format : Up to 4 digits (up to two decimal places) unitPrice Value : Cost of an item per unit excluding tax, freight, and

duty

Optional

Format : Up to 4 digits with a decimal point (no dollarsymbol). For example, 4.95


Field Description


47/91




Optional



Conditional

Format : Numeric

Notes : If a value is submitted for this field, it must be thesame ID used for the original transaction.

For more complete information, see "For RefundTransactions," page 44

customerPaymentProfileId Value : Payment gateway assigned ID associated with

the customer payment profileConditional

Format : Numeric

Notes : If a value is submitted for this field, it must be thesame ID used for the original transaction.

For more complete information, see "For RefundTransactions," page 44 .


Optional

Format : Numeric



creditCardNumberMasked Value : The last four digits of the credit card number to berefunded

Conditional

Format : Four Xs followed by the last four digits of thecredit card number to be refunded.

For example, XXXX1234Notes : If a value is submitted, the last four digits must bethe same ones used for the original transaction.



Field Description


48/91



bankRoutingNumberMasked Value : The last four digits of the routing number to berefunded

ConditionalFormat : Four Xs followed by the last four digits of therouting number to be refunded.

For example, XXXX1234

Notes : If a value is submitted, the last four digits must bethe same ones used for the original transaction.


bankAccountNumberMasked Value : The last four digits of the bank account number tobe refunded

ConditionalFormat : Four Xs followed by the last four digits of thebank account to be refunded.

For example, XXXX1234

Notes : If a value is submitted, the last four digits must bethe same ones used for the original transaction.



Optional


Optional



Optional



Optional


transId Value : The payment gateway assigned transaction ID ofthe original transaction.

Conditional

Format : Numeric

Notes : For more complete information, see "For RefundTransactions," page 44 .


Field Description


49/91



For information about output parameters for this function, see the section of this documenttitled "Input Parameters for CreateCustomerProfileTransaction."

For a Void TransactionThe following table lists the input parameters for executing an API call to theCreateCustomerProfileTransaction function for a Void transaction.


OptionalFormat : String

Notes : For a complete list of the transaction variablenames available, review the AIM Implementation Guide located at http://www.authorize.net/support/AIM_guide.pdf.


Field Description


Field Description

transaction Value : Contains transaction information


profileTransVoid Value : The transaction type that is being requested

Type : ProfileTransVoidType

Notes : Only one transaction type is allowed per request.

customerProfileId Value : Payment gateway assigned ID associated with thecustomer profile

Conditional

Format : Numeric

Notes : If a value is submitted for this field, it must be the sameID used for the original transaction.

customerPaymentProfileId Value : Payment gateway assigned ID associated with thecustomer payment profile

ConditionalFormat : Numeric

Notes : If a value is submitted for this field, it must be the sameID used for the original transaction.


50/91


51/91



The following table lists the input parameters for executing an API call to theDeleteCustomerPaymentProfile function.

For information about output parameters for this function, see the section of this documenttitled "Output for DeleteCustomerPaymentProfileResponse."

Input Parameters forDeleteCustomerShippingAddressThis function is used to delete a customer shipping address from an existing customerprofile.

The following table lists the input parameters for executing an API call to theDeleteCustomerShippingAddress function.

For information about output parameters for this function, see the section of this document"Output for DeleteCustomerShippingAddressResponse."

Input Parameters for GetCustomerProfileIdsThis function is used to retrieve all existing customer profile IDs.

Table 15 Input Parameters for DeleteCustom erPaymentProfil e

Field Description

customerProfileId Value : Payment gateway-assigned ID associated with the customer profile

Format : Numeric

customerPaymentProfileId Value : Payment gateway assigned ID associated with the customerpayment profile

Format : Numeric

Table 16 Input Parameters for DeleteCustom erShippingA ddress

Field DescriptioncustomerProfileId Value : Payment gateway-assigned ID associated with the customer profile

Format : Numeric

customerShippingAddressId Value : Payment gateway-assigned ID associated with the customershipping address

Format : Numeric


52/91



The following table lists the input parameters for executing an API call to theGetCustomerProfileIds function.

For information about output parameters for this function, see the section of this documenttitled "Output for GetCustomerProfileIdsResponse."

Input Parameters for GetCustomerProfileThis function is used to retrieve an existing customer profile along with all the associatedpayment profiles and shipping addresses.

The following table lists the input parameters for executing an API call to theGetCustomerProfile function.

For information about output parameters for this function, see the section of this documenttitled "Output for GetCustomerProfileResponse."

Table 17 Input Parameters for GetCustomerProfi leIds

Field Description

merchantAuthentication Value : Contains unique merchant information for purposes of authentication

name Value : The valid API Login ID for the developer test or merchant account


Notes : Submit the API Login ID used to submit transactions

transactionKey Value : The valid Transaction Key for the developer test or merchant account


Notes : Submit the Transaction Key obtained from the Merchant Interface

Table 18 Input Parameters for GetCustomerProfile

Field Description

customerProfileId Value : Payment gateway-assigned ID associated with the customerprofile

Format : Numeric


53/91



Input Parameters forGetCustomerPaymentProfileThis function is used to retrieve a customer payment profile for an existing customerprofile.

The following table lists the input parameters for executing an API call to theGetCustomerPaymentProfile function.

For information about output parameters for this function, see the section of this documenttitled "Output for GetCustomerProfileResponse."

Input Parameters forGetCustomerShippingAddress

This function is used to retrieve a customer shipping address for an existing customerprofile.

The following table lists the input parameters for executing an API call to theGetCustomerShippingAddress function.

For information about output parameters for this function, see the section of this documenttitled "Output for GetCustomerShippingAddressResponse."

Table 19 Input Parameters for GetCustomerPaymentProfile

Field Description

customerProfileId Value : Payment gateway-assigned ID associated with thecustomer profile

Format : Numeric

customerPaymentProfileId Value : Payment gateway-assigned ID associated with thecustomer payment profile

Format : Numeric

Table 20 Input Parameters for GetCustomerShippingAddress

Field Description


Format : Numeric

customerShippingAddressId Value : Payment gateway-assigned ID associated with the customershipping address

Format : Numeric


54/91



Input Parameters for GetHostedProfilePageUse this function to initiate a request for direct access to the Authorize.Net website. Formore information on using the hosted form, see "Using a Hosted Form," page 82 .

The following table lists the input parameters for executing an API call to theGetHostedProfilePage function.

Example st r i ng st r i ng 111111 st r i ng st r i ng st r i ng st r i ng

Table 21 Input Parameters for GetHostedProfilePage

Field Description


Format: Numeric

hostedProfileSettings Value : Optional. This is an array of settings for the session.

settingName Value : Optional. One of:

hostedProfileReturnUrl

hostedProfileReturnUrlTexthostedProfileHeadingBgColor

hostedProfilePageBorderVisible

hostedProfileIFrameCommunicatorUrl

hostedProfileValidationMode

settingValue Value : See "Guidelines for Parameter Settings," page 85 for a detailed descriptionof these parameters.


55/91



Input Parameters for UpdateCustomerProfileThis function is used to update an existing customer profile.

The following table lists the input parameters for executing an API call to theUpdateCustomerProfile function.

For information about output parameters for this function, see the section of this documenttitled "Output for UpdateCustomerProfileResponse."

Input Parameters forUpdateCustomerPaymentProfileThis function is used to update a payment profile for an existing customer profile.

Table 22 Input Parameters for UpdateCustomerProfile

Field Description

profile Value : Contains payment information for the customer profile

Type : CustomerProfileExType

merchantCustomerId Value : Merchant assigned ID for the customer

OptionalFormat: Up to 20 characters

description Value : Description of the customer or customer profile

Optional

Format: Up to 255 characters

email Value : Email address associated with the customer profile

Optional



Format: Numeric


56/91



The following table lists the input parameters for executing an API call to theUpdateCustomerPaymentProfile function.

Note

If some fields in this request are not submitted or are submitted with a blankvalue, the values in the original profile are removed. As a best practice to

prevent this from happening, call Get Cust omer Payment Pr of i l e beforecalling Updat eCust omer Payment Pr of i l e . That will return all currentinformation including masked payment information. Then, simply change thefield that needs updating and use that to callUpdat eCust omer Payment Pr of i l e .

Table 23 Input Parameters for UpdateCustomerPaymentProfil e

Field Description


Format: Numeric

paymentProfile Value : Contains payment information for the customer profile

Type : CustomerPaymentProfileExType

Notes : Sensitive information that is not being updated can be masked.

customerType Optional

Type : CustomerTypeEnum

Format: individual or business

Notes : If this field is not submitted in the request, or submitted with a blankvalue, the original value will be removed from the profile.

billTo Type : CustomerAddressType

Notes : If this entire section is not submitted, the original billing informationfor the profile will stay the same.

If updating only one or more elements under billTo, all elements must besubmitted with their valid values to prevent the original values from beingremoved.


Optional

Format: Up to 50 characters (no symbols)

Notes : If this field is not submitted in the request, or submitted with a blank

value, the original value will be removed from the profile.lastName Value : The customers last name

Optional

Format: Up to 50 characters (no symbols)



57/91


58/91



faxNumber Value : The fax number associated with the customers address

Optional

Format: Up to 25 digits (no letters)

For example, (123)123-1234


payment Value : Contains payment information for the customer profile

Type : PaymentSimpleType

Notes : Can contain CreditCardSimpleType or BankAccountType.

creditCard Value : Contains credit card payment information for the customer profile

Conditional

Type : CreditCardSimpleTypeNotes : This parameter and its children are only required when thepayment profile is credit card.

cardNumber Value : The customers credit card number

Format: 13 to 16 digits

Number can also be masked, for example, XXXX1111

Notes : If the value is masked, the last four digits must match the originalvalue in the profile.

If a masked value is submitted, the original value will not be updated.

expirationDate Value : The expiration date for the customers credit card

Format: YYYY-MM

Number can also be masked, for example, XXXX

Notes : If a masked value is submitted, the original value will not beupdated.

For .Net users, the classSystem.Runtime.Remoting.Metadata.W3cXsd2001.SoapYearMonth canbe used to manage gYearMonth types.

cardCode Value : The three- or four-digit number on the back of a credit card (on thefront for American Express)

Optional

Format: Numeric

Notes : This field is required if the merchant would like to use the CardCode Verification (CCV) security feature. For more information, see theMerchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

cardCode is only used for validation and is not stored in the customerprofile. It should only be used when submitting validationMode with a valueof testMode or liveMode.

Table 23 Input Parameters for UpdateCustom erPaymentProfil e (Continued)

Field Description
http://www.authorize.net/support/Merchant/default.htmhttp://www.authorize.net/support/Merchant/default.htmhttp://www.authorize.net/support/Merchant/default.htmhttp://www.authorize.net/support/Merchant/default.htm


59/91



bankAccount Value : Contains bank account payment information for the customer profile

Conditional


Notes : This parameter and its children are only required when thepayment profile is bank account.


Optional

type : BankAccountTypeEnum

Format: checking, savings, or businessChecking



Format: 9 digits


Notes : If the value is masked, the last four digits must match the originalvalue in the profile.

If a masked value is submitted, the original value will not be updated.


Format: 5 to 17 digits


Notes : If the value is masked, the last four digits must match the original

value in the profile.If a masked value is submitted, the original value will not be updated.

nameOnAccount Value : The customers full name as listed on the bank account




Optional


Format: CCD, PPD, TEL, or WEBNotes : Currently, the CIM API does not support ARC or BOC transactiontypes.

If this field is not submitted in the request, or submitted with a blank value,the original value will be removed from the profile.


Field Description


60/91



To test the validity of new payment information, call ValidateCustomerPaymentProfile aftersuccessfully updating the payment profile. See the section of this document titled "InputParameters for ValidateCustomerPaymentProfile" for more information.

For information about output parameters for this function, see the section of this documenttitled "Input Parameters for UpdateCustomerPaymentProfile."

Input Parameters forUpdateCustomerShippingAddressThis function is used to update a shipping address for an existing customer profile.

The following table lists the input parameters for executing an API call to theUpdateCustomerShippingAddress function.


Optional



customerPaymentProfileId Value : Payment gateway-assigned ID associated with the customerpayment profile

Format: Numeric


Format: none, testMode, or liveMode

Notes : For more information on use and restrictions of validationMode,see "The validationMode Parameter," page 14 .


Field Descriptio

Documents

Merchant Web Services API Customer Information Manager (CIM) SOAP Guide