India : 011-32914285 | Outside :+91-11-32914285

India : 09310894285 | Outside :+ 91- 9310894284

Office Hours: M-F 9:30AM - 5:30PM CST
Email ::bageshsingh@gmail.com

Bagesh Singh Web Developer

the shortest distance to a classifieds and auction software solution

Recent Projects

Flower Galaxy India

This site is a fully shopping cart which have good design and good class based programming used to create it.

<< >> Play > Stop

Technology I Know

Authorize.net : AIM , CIM

Advanced Integration Method (AIM)

Developer Guide

Card Not Present Transactions

Authorize.Net Developer Support

http://developer.authorize.net

Authorize.Net LLC 082007 Ver.2.0

Last revised: 8/21/2009

Authorize.Net LLC (“Authorize.Net”) has made efforts to ensure the accuracy and completeness of the information 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 or damage, whether direct, indirect, incidental, consequential, special or exemplary, with respect to (a) the information; 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 existing or 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 technology associated with the Authorize.Net services. No title or ownership of any of the foregoing is granted or otherwise transferred hereunder. Authorize.Net reserves the right to make changes to any information herein without further notice.

Authorize.Net Trademarks:

Advanced Fraud Detection Suite™

Authorize.Net®

Authorize.Net Your Gateway to IP Transactions™

Authorize.Net Verified Merchant Seal™ Authorize.Net Where the World Transacts®

Automated Recurring Billing™

eCheck.Net®

FraudScreen.Net®

Last revised: 8/21/2009

Table of Contents

Revision History ................................................................................. 4

Section 1............................................................................................. 5

Introduction........................................................................................ 5

AIM Minimum Requirements ...........................................................................................5

Payment Card Industry (PCI) Data Security Standard ........................................................... 6

Managing Integration Settings.........................................................................................6

Features of AIM...............................................................................................................7

eCheck.Net®...................................................................................................................7

Developer Support ..........................................................................................................8

Section 2............................................................................................. 9

Submitting Transactions ................................................................... 9

Minimum Requirements ..................................................................................................9

Credit Card Transaction Types......................................................................................11

Authorization and Capture...................................................................................................... 12

Authorization Only................................................................................................................... 12

Prior Authorization and Capture ............................................................................................ 12

Capture Only ............................................................................................................................ 13

Credit........................................................................................................................................ 13

Unlinked Credit ........................................................................................................................ 14

Void .......................................................................................................................................... 14

Using the Merchant Interface ........................................................................................15

Section 3........................................................................................... 16

Transaction Data Requirements...................................................... 16

Transaction Post Location.............................................................................................16

AIM Transaction Submission API ..................................................................................16

Merchant Information .............................................................................................................. 16

Transaction Information.......................................................................................................... 17

Order Information .................................................................................................................... 20

Itemized Order Information..................................................................................................... 20

Customer Information ............................................................................................................. 21

Shipping Information............................................................................................................... 23

Additional Shipping Information (Level 2 Data) ................................................................... 23

Cardholder Authentication ..................................................................................................... 25

Merchant-defined fields .......................................................................................................... 27

Section 4........................................................................................... 29

Transaction Response ..................................................................... 29

Fields in the Payment Gateway Response ....................................................................30

Response for Duplicate Transactions ................................................................................... 34

Response Code Details.................................................................................................35

Response Codes...................................................................................................................... 36

Response Reason Codes and Response Reason Text ....................................................... 37

Email Receipt ................................................................................................................46

Section 5........................................................................................... 48

Table of Contents

Last revised: 8/21/2009

Test Transactions ............................................................................ 48

Testing to Generate Specific Transaction Results............................................................... 49

Appendix A ....................................................................................... 50

Fields by Transaction Type ............................................................. 50

Minimum Required Fields..............................................................................................50

Required Fields for Additional AIM Features .................................................................50

Best Practice Fields.......................................................................................................51

Appendix B ....................................................................................... 52

Alphabetized List of API Fields........................................................ 52

Last revised: 8/21/2009

Revision History

PUBLISH DATE

UPDATES

August 2007

Release of Ver 2.0 Advanced Integration Method (AIM) Developer Guide

May 2008

Remove SecureSource requirements and various updates

March 2009

Addition of error codes 315-319

July 2009

Clarify use of x_recurring_billing, x_version

Added warning for Merchant Defined Fields

Additions to the Response Code list

Last revised: 8/21/2009

Section 1

Introduction

Welcome to the Authorize.Net Advanced Integration Method (AIM) Developer Guide. This guide describes the Web development required to connect an e-commerce Web site or other application to the Authorize.Net Payment Gateway in order to submit credit card transactions for authorization and settlement using AIM.

AIM is a customizable payment processing solution that gives the merchant control over all the steps in processing a transaction, including:

• Collection of customer payment information through a custom application

• Generation of a receipt to the customer

• Secure transmission to the payment gateway for transaction processing

• Secure storage of cardholder information

• And more, depending on the merchant’s business requirements

The security of an AIM transaction is assured through a 128-bit Secure Sockets Layer (SSL) connection between the merchant’s Web server and the Authorize.Net Payment Gateway.

AIM is an ideal integration solution because it allows merchants the highest degree of customization and control over their customers’ checkout experience.

Note: For merchants who prefer a payment solution that handles the collection, transmission and storage of cardholder data, Authorize.Net recommends the Server Integration Method (SIM). The SIM Developer Guide can be found in the Authorize.Net Integration Center at http://developer.authorize.net/guides/SIM/default.htm.

With SIM, merchants never have to collect, transmit, or store sensitive cardholder information. Additionally, SIM does not require merchants to purchase and install a Secure Sockets Layer (SSL) digital certificate. This removes the complexity of securely handling and storing cardholder information, simplifying compliance with the Payment Card Industry (PCI) Data Security Standard.

AIM Minimum Requirements

Before you begin, check with the merchant to make sure that the following AIM requirements have already been met. It is strongly recommended that you work closely with the merchant to ensure that any other business and Web site requirements (for example, bank or processor requirements, Web site design preferences) are included in their AIM integration.

Section 1 Introduction

Last revised: 8/21/2009

• The merchant must have a U.S. based merchant bank account that allows Internet transactions.

• The merchant must have an e-commerce (Card Not Present) Authorize.Net Payment Gateway account.

• The merchant must have a valid Secure Sockets Layer (SSL) certificate and their Web site must be capable of initiating both client and server side SSL connections.

• The merchant’s Web site must have server-side scripting or CGI capabilities such as ASP Classic, C#, Cold Fusion, Java, Perl, PHP or VB.Net.

• The merchant must be able to store payment gateway account data securely (for example, API Login ID, Transaction Key, Secret Answer).

Payment Card Industry (PCI) Data Security Standard

IMPORTANT: AIM involves the transmission of sensitive cardholder data by means of the merchant’s Web server. As such, the merchant is required to store cardholder information securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. For more information about PCI and other industry standard processing practices, please see the Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf for more information.

If the merchant needs a solution that handles the collection, transmission and storage of cardholder data, they should use the Server Implementation Method (SIM). For more information about SIM, please see the SIM Developer Guide at http://developer.authorize.net/guides/SIM/default.htm.

Managing Integration Settings

When integrating to the payment gateway, you should be aware that most settings for a merchant’s integration can be configured and managed in two ways:

1. Included in the transaction request on a per-transaction basis using the application programming interface (API), (as described in this guide), OR

2. Configured in the Merchant Interface and applied to all transactions.

IMPORTANT: The Merchant Interface at https://secure.authorize.net is a secure Web site where merchants can manage their payment gateway account settings, including their Web site integration settings. It is recommended that you review the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm for information on managing the merchant’s payment gateway integration using the Merchant Interface.

Transaction settings submitted in the transaction request will override transaction settings configured in the Merchant Interface. However, please be aware that some integration settings must be configured in the Merchant Interface. To help the merchant maintain a robust integration, it is recommended that you review the integration settings that can be configured in the Merchant Interface with the merchant and determine which integration settings can be posted on a per-transaction basis and which should be configured in the Merchant Interface. See the “Appendix

WebLink Developer Guide

Last revised: 8/21/2009

A Fields by Transaction Type” section of this document for a list of fields the payment gateway recommends be submitted on a per-transaction basis.

Features of AIM

In addition to basic transaction processing, AIM provides merchants with several features for configuring transaction security options and further customizing their customers’ checkout experience. These features are listed in the AIM Feature Selection Guide provided below. Please take a few moments to discuss these with your merchant and select which features they would like to include in their integration.

FEATURE

DESCRIPTION

REQUIREMENTS



Address Verification Service (AVS) Filter

This feature allows merchants to compare the billing address submitted by the customer for the transaction with the address on file at the card issuing bank. Filter settings in the Merchant Interface allow the merchant to reject transactions based on the AVS response received.

To implement AVS, the merchant must require the Address and ZIP Code fields on their custom payment form.

For more information about AVS, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.



Card Code Verification (CCV) Filter

This feature allows merchants to compare the card code submitted by the customer for the transaction with the card code on file at the card issuing bank. Filter settings in the Merchant Interface allow the merchant to reject transactions based on the CCV response received.

To implement CCV, the merchant must require the Card Code on their custom payment form.

For more information about CCV, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.



Itemized Order Information

This feature allows merchants to submit details for items purchased. This information is included in the merchant transaction confirmation email, in the Transaction Details for the transaction and in QuickBooks download reports in the Merchant Interface.

To implement Itemized Order Information, the line item field must be submitted on a per-transaction basis.

Please see the “Itemized Order Information” section of this document for details.



Email Receipt

This feature allows merchants to opt for an automatic email receipt to be sent by the payment gateway to their customers.

To configure the payment gateway email receipt, the merchant must require the customer email address on their custom payment form, and settings must be configured in the Email Receipts section of the Settings menu in the Merchant Interface or submitted on a per-transaction basis.

Please see the “Receipt Options” section of this document for details.

eCheck.Net®

In addition to processing credit card transactions, the payment gateway also supports electronic check transactions with our exclusive eCheck.Net® product. Please contact the merchant to determine whether eCheck.Net is enabled for their payment gateway account or if they would like to sign up. In the event that eCheck.Net is enabled, you will need to ensure that the merchant’s Web site integration supports all eCheck.Net field requirements. Please see the eCheck.Net Developer Guide at http://developer.authorize.net/guides/eCheck.pdf for more information.

Section 1 Introduction

Last revised: 8/21/2009

Developer Support

There are several resources available to help you successfully integrate a merchant Web site or other application to the Authorize.Net Payment Gateway.

• The Integration Center at http://developer.authorize.net provides test accounts, sample code, FAQs, and troubleshooting tools.

• If you can’t find what you need in the Integration Center, our Integration Team is available to answer your questions by email at integration@authorize.net. (Our Integration Team can only assist with support requests specifically about the Authorize.Net application programming interface (API) and/or services.)

• Be sure to read our Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf for information on how to maximize the security and reliability of your merchant integration solutions.

If you have any suggestions about how we can improve or correct this guide, please email documentation@authorize.net.

Last revised: 8/21/2009

Section 2

Submitting Transactions

The payment gateway supports several credit card transaction types for transactions submitted by AIM.

To implement AIM for a merchant’s Web site or proprietary business application, you will need to develop an application that performs the following:

• Securely obtains all of the information required to process a transaction (including data requirements specified by the merchant).

• Initiates a secure SSL connection from the merchant’s Web server to the payment gateway transaction post location to pass transaction data in name/value pairs.

• Receives and parses the transaction response from the payment gateway and displays the results to the customer.

There are two options for developing the application:

• You can develop a custom application yourself using the information provided in this document, OR

• You can use Authorize.Net sample code available for free from our Integration Center at http://developer.authorize.net.

If you choose to use sample code, please be aware that to achieve a successful implementation it must be modified with the merchant’s specific payment gateway account information. Be sure to carefully review the readme.txt files and comments included in each file of sample code in order to achieve a faster, successful integration.

Developer test accounts with API Login IDs and Transaction Keys are also available for testing your integration methods to the Authorize.Net Payment Gateway at http://developer.authorize.net/testaccount.

Minimum Requirements

The following table represents the minimum fields required for submitting a credit card transaction request to the payment gateway using AIM. The data fields are name/value pairs with the syntax of:

x_name_of_field=value of field&.

Section 2 Submitting Transactions

Last revised: 8/21/2009

FIELD NAME

VALUE

FORMAT

NOTES

x_login

The merchant’s unique API Login ID

Up to 20 characters

The merchant API Login ID is provided in the Merchant Interface and must be stored securely.

The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway.

See the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm for more information.

x_tran_key

The merchant’s unique Transaction Key

16 characters

The merchant Transaction Key is provided in the Merchant Interface and must be stored securely.

The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway.

See the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm for more information.

x_type

The type of credit card transaction

AUTH_CAPTURE (default), AUTH_ONLY, CAPTURE_ONLY, CREDIT, PRIOR_

AUTH_CAPTURE, VOID

If the value submitted does not match a supported value, the transaction is rejected. If this field is not submitted or the value is blank, the payment gateway will process the transaction as an AUTH_CAPTURE.

x_amount

The amount of the transaction

Up to 15 digits with a decimal point (no dollar symbol)

Ex. 8.95

This is the total amount and must include tax, shipping, and any other charges.

x_card_num

The customer’s credit card number

Between 13 and 16 digits without spaces

When x_type=CREDIT, only the last four digits are required.

This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.

For more information about PCI, please see the Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf.

x_exp_date

The customer’s credit card expiration date

MMYY,

MM/YY,

MM-YY, MMYYYY, MM/YYYY,

MM-YYYY

This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.

For more information about PCI, please see the Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf.

AIM Developer Guide

Last revised: 8/21/2009

FIELD NAME

VALUE

FORMAT

NOTES

x_trans_id

The payment gateway assigned transaction ID of an original transaction

Required only for CREDIT, PRIOR_AUTH_CAPTURE, and VOID transactions.

For more information about transaction types, see the “Credit Card Transaction Types” section of this document.

x_auth_code

The authorization code of an original transaction not authorized on the payment gateway

6 characters

Required only for CAPTURE_ONLY transactions. See the “Credit Card Transaction Types” section below.

x_relay_response

FALSE

FALSE, F, NO, N, 0

SIM applications use relay response. Set this to false if you are using AIM.

x_delim_data

Indicates whether a delimited transaction response is required

TRUE, FALSE,

T,F,

YES, NO,

Y, N,

1, 0

A value of TRUE indicates a request for delimited response from the payment gateway. Since all AIM transactions are direct response, a value of TRUE is required.

It is recommended that you submit this field on a per-transaction basis to be sure that transaction responses are returned in the correct format.

See Transaction Response below for more about delimited response

Credit Card Transaction Types

This section describes the credit card transaction types supported by the payment gateway and their specific field requirements. It’s a good idea to talk to your merchant about how their business plans to submit transaction so that you can properly integrate their payment gateway account to support their business processes.

For example, are they submitting transactions mainly through an e-commerce Web site? Do they need to integrate a custom application to allow call center representatives to enter mail order/telephone order (MOTO) transactions? Would they like the ability to verify the availability of funds on a customer’s credit card account at the time of purchase and then charge the credit card at the time they ship the order?

The payment gateway supports the following credit card transaction types.

Note: Some of the field requirements listed in this section for each credit card transaction type are in addition to the minimum field requirements already set forth above for ALL transactions submitted to the payment gateway. For a list of all fields that are required for each credit card transaction type, please see the “Appendix A Fields by Transaction Type” section of this document.

Section 2 Submitting Transactions

Last revised: 8/21/2009

Authorization and Capture

This is the most common type of credit card transaction and is the default payment gateway transaction type. The amount is sent for authorization, and if approved, is automatically submitted for settlement.

The unique field requirement for an Authorization and Capture is:

• x_type=AUTH_CAPTURE

Authorization Only

This transaction type is sent for authorization only. The transaction will not be sent for settlement until the credit card transaction type Prior Authorization and Capture (see definition below) is submitted, or the transaction is submitted for capture manually in the Merchant Interface. For more information about capturing Authorization Only transactions in the Merchant Interface, see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

If action for the Authorization Only transaction is not taken on the payment gateway within 30 days, the authorization expires and is no longer available for capture. A new Authorization Only transaction would then have to be submitted to obtain a new authorization code.

The unique field requirement for an Authorization Only is:

• x_type=AUTH_ONLY

Merchants can submit Authorization Only transactions if they want to verify the availability of funds on the customer’s credit card before finalizing the transaction. This transaction type can also be submitted in the event that the merchant does not currently have an item in stock or wants to review orders before shipping goods.

Prior Authorization and Capture

This transaction type is used to complete an Authorization Only transaction that was successfully authorized through the payment gateway.

Note: An Authorization Only and a Prior Authorization and Capture together are considered one complete transaction. Once the Prior Authorization and Capture is submitted, the transaction will be sent for settlement.

The payment gateway accepts this transaction type and initiates settlement if the following conditions are met:

• The original Authorization Only transaction was submitted within the previous 30 days (Authorization Only transactions expire on the payment gateway after 30 days).

• The transaction is submitted with the valid transaction ID (x_trans_id) of an original, successfully authorized, Authorization Only transaction.

• The original transaction is not yet captured, expired or errored.

AIM Developer Guide

Last revised: 8/21/2009

• The amount being requested for capture is less than or equal to the original authorized amount. Only a single Prior Authorization and Capture transaction can be submitted against an Authorization Only.

The unique field requirements for a Prior Authorization and Capture are:

• x_type=PRIOR_AUTH_CAPTURE

• x_trans_id=Transaction ID here

For this transaction type, the amount field (x_amount) is only required in the event that a Prior Authorization and Capture is submitted for an amount that is less than the amount of the original Authorization Only transaction. If no amount is submitted, the payment gateway will initiate settlement for the amount of the original authorized transaction.

Capture Only

This transaction type is used to complete a previously authorized transaction that was not originally submitted through the payment gateway or that requires voice authorization.

A Capture Only transaction is most commonly submitted in the Merchant Interface to manually accept a transaction that was declined by the payment gateway due to Address Verification Service (AVS) and/or Card Code Verification (CCV) filtering. For more information about overriding AVS and CCV filter declines, see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

The payment gateway accepts this transaction type and initiates settlement if the following conditions are met:

• The transaction is submitted with the valid authorization code issued to the merchant to complete the transaction.

The unique field requirements for a Capture Only are:

• x_type=CAPTURE_ONLY

• x_auth_code=Authorization Code here

For instructions on how to perform a Capture Only transaction in the Merchant Interface, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

Credit

This transaction type is used to refund a customer for a transaction that was originally processed and successfully settled through the payment gateway.

The payment gateway accepts Credits if the following conditions are met:

• The transaction is submitted with the valid transaction ID (x_trans_id) of an original, successfully settled transaction.

• The amount being requested for refund is less than or equal to the original settled amount.

Section 2 Submitting Transactions

Last revised: 8/21/2009

• The sum amount of multiple Credit transactions submitted against the original transaction is less than or equal to the original settled amount.

• At least the last four digits of the credit card number (x_card_num) used for the original, successfully settled transaction are submitted. An expiration date is not required.

• The transaction is submitted within 120 days of the settlement date of the original transaction.

The unique field requirements for a Credit are:

• x_type=CREDIT

• x_trans_id=Transaction ID here

• x_card_num=Full credit card number or last four digits only here

Unlinked Credit

This transaction type is used to issue a refund for a transaction that was not originally submitted through the payment gateway. It also allows the merchant to override restrictions for submitting refunds for payment gateway transactions, for example, if the merchant is beyond the 120-day period for submitting a refund or would like to refund an amount that is greater than the original transaction amount.

The ability to submit unlinked credits is not a standard feature of a merchant’s payment gateway account. To be enabled for expanded credits capability (ECC), the merchant must submit an application. For more information about the ECC application, please see the http://www.authorize.net/files/ecc.pdf.

IMPORTANT: A transaction ID must not be submitted with an Unlinked Credit. If ECC is enabled for the merchant’s account, and a transaction ID is submitted with the Unlinked Credit transaction, then the payment gateway will attempt to apply the credit to an original transaction with the transaction ID submitted.

The unique field requirement for an Unlinked Credit is:

• x_type=CREDIT

Void

This transaction type is used to cancel an original transaction that is not yet settled and prevents it from being sent for settlement. A Void can be submitted against any other transaction type.

Note: If you are unsure of whether a transaction is settled, you can attempt to submit a Void first. If the Void transaction errors, the original transaction is likely settled and you can submit a Credit for the transaction.

The payment gateway accepts Voids if the following conditions are met:

AIM Developer Guide

Last revised: 8/21/2009

• The transaction is submitted with the valid transaction ID (x_trans_id) of an original, successfully authorized transaction.

• The original transaction is not already settled, expired or errored.

The unique field requirements for a Void are:

• x_type=VOID

• x_trans_id=Transaction ID here

Note: Typically, Authorization Only or Authorization and Capture are the primary transaction types submitted by an e-commerce Web site or other application. Though they most likely will not be used for the merchant’s Web site integration, all other transaction types listed above can be integrated for automatic submission into an internal or enterprise application, like those used in a call center, or they can also be submitted by the merchant manually using the Virtual Terminal in the Merchant Interface.

Using the Merchant Interface

The Merchant Interface allows merchants to manage transactions, capture Authorization Only transactions, void transactions, and issue refunds. These transaction types can also be managed automatically using the API if you are integrating a custom application to the payment gateway. However, for most integrations, these transaction types can be more conveniently and easily managed in the Merchant Interface.

For more information on submitting transactions in the Merchant Interface, see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm or click Help in the top right corner of the Merchant Interface.

Last revised: 8/21/2009

Section 3

Transaction Data Requirements

The standard payment gateway application programming interface (API) consists of required information fields (introduced in the previous section) and additional optional fields that can be submitted to the payment gateway for real-time transaction processing.

Transaction Post Location

The merchant’s Web site should submit transaction requests to the following payment gateway URL:

https://secure.authorize.net/gateway/transact.dll

Note: If you are developing using an Authorize.Net developer test account, test transactions are posted to a staging environment at https://test.authorize.net/gateway/transact.dll. If you do not have a developer test account, you can sign up for one at http://developer.authorize.net.

AIM Transaction Submission API

The following tables list the transaction data fields that can be submitted using the transaction request string. Several of these fields can also be configured in the Merchant Interface. For more information about configuring these settings in the Merchant Interface, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

Fields are name/value pairs with the syntax:

x_name_of_field = value of the field&.

Merchant Information

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_login

Required

The merchant’s unique API Login ID

Up to 20 characters

The merchant API Login ID is provided in the Merchant Interface and must be stored securely.

The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway.

See the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm for more information.

AIM Developer Guide

Last revised: 8/21/2009

x_tran_key

Required

The merchant’s unique Transaction Key

16 characters

The merchant Transaction Key is provided in the Merchant Interface and must be stored securely.

The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway.

See the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm for more information.

Transaction Information

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_version

Required

The merchant’s transaction version

3,0, 3.1

Indicates to the system the set of fields that will be included in the response:

3.0 is the default version.

3.1 allows the merchant to utilize the Card Code feature, and is the current standard version.

It is highly recommended that you submit this field on a per-transaction basis to be sure that the formats of transaction requests and the responses you receive are consistent.

For more information, see the “Appendix A Fields by Transaction Type” sections of this document.

x_type

Optional

The type of credit card transaction

AUTH_CAPTURE (default), AUTH_ONLY, CAPTURE_ONLY, CREDIT, PRIOR_

AUTH_CAPTURE, VOID

x_method

Optional

The payment method

CC or ECHECK

The method of payment for the transaction, CC (credit card) or ECHECK (electronic check). If this field is not submitted or is blank, the value will default to CC.

For more information about eCheck.Net transaction requirements, see the eCheck.Net Developer Guide at http://developer.authorize.net/guides/eCheck.pdf.

Section 3 Transaction Data Requirements

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_recurring_billing

Optional

The recurring billing status

TRUE, FALSE,

T, F,

YES, NO,

Y, N,

1, 0

Indicating marker used by merchant account providers to identify transactions which originate from merchant hosted recurring billing applications. This value is not affiliated with Automated Recurring Billing.

x_amount

Required

The amount of the transaction

Up to 15 digits with a decimal point (no dollar symbol)

Ex. 8.95

This is the total amount and must include tax, shipping, and any other charges. The amount can either be hard coded or posted to a script.

x_card_num

Required

The customer’s credit card number

Between 13 and 16 digits without spaces

When x_type=CREDIT, only the last four digits are required.

This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.

For more information about PCI, please see the Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf.

x_exp_date

Required

The customer’s credit card expiration date

MMYY,

MM/YY,

MM-YY, MMYYYY, MM/YYYY,

MM-YYYY

This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.

For more information about PCI, please see the Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf.

x_card_code

Optional

The customer’s card code

Numeric

The three- or four-digit number on the back of a credit card (on the front for American Express).

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

Cardholder information must be stored securely and in accordance with the Payment

AIM Developer Guide

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

Card Industry (PCI) Data Security Standard.

Please see the Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf for more information.

x_trans_id

Conditional

Required only for CREDIT, PRIOR_ AUTH_ CAPTURE, and VOID transactions

The payment gateway assigned transaction ID of an original transaction

For more information about transaction types, see the “Credit Card Transaction Types” section of this document.

x_auth_code

Conditional

Required only for CAPTURE_ ONLY transactions

The authorization code of an original transaction not authorized on the payment gateway

6 characters

See the “Credit Card Transaction Types” section of this document.

x_test_request

Optional

The request to process test transactions

TRUE, FALSE,

T, F,

YES, NO,

Y, N,

1, 0

Indicates if the transaction should be processed as a test transaction.

See the “Test Transactions” section of this guide for more information.

x_duplicate_window

Optional

The window of time after the submission of a transaction that a duplicate transaction can not be submitted

Any value between 0 and 28800 (no comma)

Indicates in seconds the window of time after a transaction is submitted during which the payment gateway will check for a duplicate transaction. The maximum time allowed is 8 hours (28800 seconds).

If a value less than 0 is sent, the payment gateway will default to 0 seconds. If a value greater than 28800 is sent, the payment gateway will default to 28800. If no value is sent, the payment gateway will default to 2 minutes (120 seconds).

If this field is present in the request with or without a value, an enhanced duplicate transaction response is sent. See the “Response for Duplicate Transactions”

Section 3 Transaction Data Requirements

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

section of this guide for more information.

Order Information

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_invoice_num

Optional

The merchant assigned invoice number for the transaction

Up to 20 characters (no symbols)

The invoice number must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function.

x_description

Optional

The transaction description

Up to 255 characters (no symbols)

The description must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function.

Itemized Order Information

Based on their respective business requirements, merchants can choose to submit itemized order information with a transaction. Itemized order information is not submitted to the processor and is not currently returned with the transaction response. This information is displayed on the Transaction Detail page and in QuickBooks download file reports in the Merchant Interface.

Note: The value for the x_line_item field is capable of including delimited item information. In this case, line item values must be included in the order listed below.

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_line_item

Optional

Any string

Line item values must be delimited by a bracketed pipe <|>

Itemized order information.

Item ID<|>

Up to 31 characters

The ID assigned to an item.

<|>item name<|>

Up to 31 characters

A short description of an item.

<|>item description<|>

Up to 255 characters

A detailed description of an item.

<|>itemX quantity<|>

Up to two decimal places

Must be a positive number

The quantity of an item.

<|>item price (unit cost)<|>

Up to two decimal places

Must be a positive number

Cost of an item per unit, excluding tax, freight, and duty.

The dollar sign ($) is not allowed when submitting delimited information.

AIM Developer Guide

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

<|>itemX taxable

TRUE, FALSE,

T, F,

YES, NO,

Y, N,

1, 0

Indicates whether the item is subject to tax.

The merchant can submit up to 30 distinct line items containing itemized order information per transaction. For example:

Sample 6. Submitting itemized order information

x_line_item=item1<|>golf balls<|><|>2<|>18.95<|>Y&x_line_item=

item2<|>golf bag<|>Wilson golf carry bag, red<|>1<|>39.99<|>Y&

x_line_item=item3<|>book<|>Golf for Dummies<|>1<|>21.99<|>Y&

Note: For Prior Authorization and Capture transactions, if line item information was submitted with the original transaction, adjusted information can be submitted in the event that the transaction changed. If no adjusted line item information is submitted, the information submitted with the original transaction will apply.

Customer Information

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_first_name

Optional

The first name associated with the customer’s billing address

Up to 50 characters (no symbols)

x_last_name

Optional

The last name associated with the customer’s billing address

Up to 50 characters (no symbols)

x_company

Optional

The company associated with the customer’s billing address

Up to 50 characters (no symbols)

x_address

Optional

The customer’s billing address

Up to 60 characters (no symbols)

Required if the merchant would like to use the Address Verification Service security feature.

For more information on AVS, see the Merchant Integration Guide at

http://www.authorize.net/support/Merchant/default.htm.

x_city

Optional

The city of the customer’s billing address

Up to 40 characters (no symbols)

x_state

Optional

The state of the customer’s billing

Up to 40 characters (no symbols) or a

Section 3 Transaction Data Requirements

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

address

valid two-character state code

x_zip

Optional

The ZIP code of the customer’s billing address

Up to 20 characters (no symbols)

Required if the merchant would like to use the Address Verification Service security feature.

For more information on AVS, see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

x_country

Optional

The country of the customer’s billing address

Up to 60 characters (no symbols)

x_phone

Optional

The phone number associated with the customer’s billing address

Up to 25 digits (no letters)

Ex. (123)123-1234

x_fax

Optional

The fax number associated with the customer’s billing address

Up to 25 digits (no letters)

Ex. (123)123-1234

x_email

Optional

The customer’s valid email address

Up to 255 characters

Ex. janedoe@customer.com

The email address to which the customer’s copy of the email receipt is sent when Email Receipts is configured in the Merchant Interface. The email is sent to the customer only if the email address format is valid.

For more information about Email Receipts, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

x_cust_id

Optional

The merchant assigned customer ID

Up to 20 characters (no symbols)

The unique identifier to represent the customer associated with the transaction.

The customer ID must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function.

x_customer_ip

Optional

The customer’s IP address

Up to 15 characters (no letters)

Ex. 255.255.255.255

IP address of the customer initiating the transaction. If this value is not passed, it will default to 255.255.255.255.

This field is required when using the Fraud Detection

AIM Developer Guide

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

Suite™ (FDS) IP Address Blocking tool. For more information about FDS, see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

Shipping Information

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_ship_to_first_name

Optional

The first name associated with the customer’s shipping address

Up to 50 characters (no symbols)

x_ship_to_last_name

Optional

The last name associated with the customer’s shipping address

Up to 50 characters (no symbols)

x_ship_to_company

Optional

The company associated with the customer’s shipping address

Up to 50 characters (no symbols)

x_ship_to_address

Optional

The customer’s shipping address

Up to 60 characters (no symbols)

x_ship_to_city

Optional

The city of the customer’s shipping address

Up to 40 characters (no symbols)

x_ship_to_state

Optional

The state of the customer’s shipping address

Up to 40 characters (no symbols) or a valid two-character state code

x_ship_to_zip

Optional

The ZIP code of the customer’s shipping address

Up to 20 characters (no symbols)

x_ship_to_country

Optional

The country of the customer’s shipping address

Up to 60 characters (no symbols)

Additional Shipping Information (Level 2 Data)

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_tax

Optional

The valid tax amount OR delimited tax information

When submitting delimited tax information, values must be delimited

The tax amount charged OR when submitting this information using the transaction request string,

Section 3 Transaction Data Requirements

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

by a bracketed pipe <|>

delimited tax information including the sales tax name, description, and amount is also allowed.

The total amount of the transaction in x_amount must include this amount.

tax item name<|>

The tax item name.

tax description<|>

The tax item description.

tax amount

The dollar sign ($) is not allowed when submitting delimited information.

The tax item amount.

The total amount of the transaction in x_amount must include this amount.

Example:

x_tax=Tax1<|>state tax<|>0.0625&

x_freight

Optional

The valid freight amount OR delimited freight information

When submitting delimited freight information, values must be delimited by a bracketed pipe <|>

The freight amount charged OR when submitting this information using the transaction request string, delimited freight information including the freight name, description, and amount is also allowed.

The total amount of the transaction in x_amount must include this amount.

freight item name<|>

The freight item name.

freight description<|>

The freight item description.

freight amount

The dollar sign ($) is not allowed when submitting delimited information.

The freight amount.

The total amount of the transaction in x_amount must include this amount.

Example:

x_freight=Freight<|>ground overnight<|>12.95&

x_duty

Optional

The valid duty amount OR delimited duty information

When submitting delimited duty information, values must be delimited by a pipe <|>

The duty amount charged OR when submitting this information using the transaction request string, delimited duty information including the duty name, description, and amount is also allowed.

The total amount of the transaction in x_amount must include this amount.

duty item name<|>

The duty item name.

duty description<|>

The duty item description.

duty amount

The dollar sign ($) is not allowed when submitting delimited information.

The duty amount.

The total amount of the transaction in x_amount must

AIM Developer Guide

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

include this amount.

Example:

x_duty=Duty1<|>export<|>15.00&

x_tax_exempt

Optional

The tax exempt status

TRUE, FALSE,

T, F,

YES, NO,

Y, N,

1, 0

Indicates whether the transaction is tax exempt.

x_po_num

Optional

The merchant assigned purchase order number

Up to 25 characters (no symbols)

The purchase order number must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function.

Note: Delimited duty, freight, and tax information are not returned in the transaction response or in the merchant confirmation email. This information is displayed only on the Transaction Detail page in the Merchant Interface.

Cardholder Authentication

The payment gateway supports the transmission of authentication fields for the following cardholder authentication programs:

• Verified by Visa

• MasterCard® SecureCode™

Merchants using a third party cardholder authentication solution can submit the following authentication values with Visa and/or MasterCard transactions.

Note: The cardholder authentication fields are currently supported only through the Chase Paymentech, FDMS Nashville, Global Payments and TSYS processors for Visa and MasterCard transactions. If cardholder authentication information is submitted for transactions processed through any other processor, it will be ignored.

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

x_authentication_

indicator

Optional

The electronic commerce indicator (ECI) value for a Visa transaction; or the universal cardholder authentication field indicator (UCAF) for a MasterCard transaction obtained by the merchant after the authentication process.

Special characters included in this value must be URL encoded.

Required only for AUTH_ONLY and AUTH_CAPTURE transactions processed through cardholder authentication programs. When submitted with other transaction types, this value is ignored.

This field is currently supported through Chase Paymentech, FDMS

Section 3 Transaction Data Requirements

Last revised: 8/21/2009

FIELD NAME

REQUIRED?

VALUE

FORMAT

NOTES

Nashville, Global Payments and TSYS.

x_cardholder_

authentication_value

Optional

The cardholder authentication verification value (CAVV) for a Visa transaction; or accountholder authentication value (AVV)/ universal cardholder authentication field (UCAF) for a MasterCard transaction obtained by the merchant after the authentication process.

Special characters included in this value must be URL encoded.

Required only for AUTH_ONLY and AUTH_CAPTURE transactions processed through cardholder authentication programs. When submitted with other transaction types, this value is ignored.

This field is currently supported through Chase Paymentech, FDMS Nashville, Global Payments and TSYS.

Invalid combinations of the x_authentication_indicator and x_cardholder_authentication_value fields will cause the transaction to generate an error.

Valid value combinations for these fields are as follows:

Visa

AUTHENTICATION INDICATOR

CARDHOLDER AUTHENTICATION VALUE

Not null

Null/Blank

Not null (some international issuers can provide a CAVV value when ECI is 7)

Null/Blank

MasterCard

AUTHENTICATION INDICATOR

CARDHOLDER AUTHENTICATION VALUE

Blank /Null

Not null

Null

For example, when the MasterCard value for x_authentication_indicator is “1,” the value for x_cardholder_authentication_value must be null. In this scenario, if a value is submitted for x_cardholder_authentication_value, the transaction fails validation and is rejected.

The authentication verification value returned by Visa or MasterCard is included in the transaction response from the payment gateway and is also included on the Transaction Detail page for the transaction in the Merchant Interface.

AIM Developer Guide

Last revised: 8/21/2009

Merchant-defined fields

Merchants can also choose to include merchant-defined fields to further customize the information included with a transaction. Merchant-defined fields are any fields that are not recognized by the payment gateway as standard application programming interface (API) fields.

For example, the merchant might want to provide a field in which customers provide specific shipping instructions and product color information. All you need to do is submit a custom field name and any accompanying text with the transaction request string—for example, shipping_instructions and product_color.

Note: Standard payment gateway fields that are misspelled are treated as merchant-defined fields.

Warning: Merchant-Defined Data fields are not intended to and MUST NOT be used to capture personally identifying information. Accordingly, Merchant is prohibited from capturing, obtaining, and/or transmitting any personally identifying information in or via the Merchant-Defined Data fields. Personally identifying information includes, but is not limited to, name, address, credit card number, social security number, driver's license number, state-issued identification number, passport number, and card verification numbers (CVV, CVC2, CVV2, CID, CVN). In the event that Authorize.Net, a CyberSource solution, discovers that Merchant is capturing and/or transmitting personally identifying information via the Merchant-Defined Data fields, whether or not intentionally, CyberSource WILL immediately suspend Merchant's account, which will result in a rejection of any and all transaction requests submitted by Merchant after the point of suspension.

Last revised: 8/21/2009

Section 4

Transaction Response

The transaction response from the payment gateway is returned as a delimited string and provides information about the status of a transaction—whether it was accepted or declined—as well as information included in the transaction request.

Fields in the response are delimited by a character that is specified in the transaction request string (x_delim_char) or configured in the Merchant Interface. The merchant server can parse this data to customize receipt messages to display or email to the customer. Transaction results are also provided in the payment gateway merchant confirmation email, and on the Transaction Detail page for the transaction in the Merchant Interface.

The following fields can be used to customize the format of the payment gateway transaction response. These settings can also be configured in the Merchant Interface. For more information about configuring these settings in the Merchant Interface, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.

Authorize.Net Developer Support(CIM)
http://developer.authorize.net
Authorize.Net LLC 082007 Ver.1.0
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 1
Authorize.Net LLC (“Authorize.Net”) has made efforts to ensure the accuracy and completeness of the information 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 or damage, whether direct, indirect, incidental, consequential, special or exemplary, with respect to (a) the information; 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 existing or 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 technology associated with the Authorize.Net services. No title or ownership of any of the foregoing is granted or otherwise transferred hereunder. Authorize.Net reserves the right to make changes to any information herein without further notice.
Authorize.Net Trademarks:
Advanced Fraud Detection Suite™
Authorize.Net®
Authorize.Net Your Gateway to IP Transactions™
Authorize.Net Verified Merchant Seal™
Authorize.Net Where the World Transacts®
Automated Recurring Billing™
eCheck.Net®
FraudScreen.Net®
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 2
Table of Contents
Revision History ................................................................................. 4
Section 1............................................................................................. 5
Developer Introduction ...................................................................... 5
Minimum Requirements ..................................................................................................5
Developer Support ..........................................................................................................5
Section 2............................................................................................. 7
Executing an API Call ........................................................................ 7
Web Service Locations ....................................................................................................7
CIM Functions .................................................................................................................8
Authentication........................................................................................................................... 9
Input Elements for createCustomerProfileRequest ............................................................. 10
Input Elements for createCustomerPaymentProfileRequest .............................................. 17
Input Elements for createCustomerShippingAddressRequest .......................................... 21
Input Elements for createCustomerProfileTransactionRequest......................................... 24
Input Elements for deleteCustomerProfileRequest ............................................................. 59
Input Elements for deleteCustomerPaymentProfileRequest .............................................. 60
Input Elements for deleteCustomerShippingAddressRequest........................................... 61
Input Elements for getCustomerProfileIdsRequest ............................................................. 62
Input Elements for getCustomerProfileRequest .................................................................. 63
Input Elements for getCustomerPaymentProfileRequest ................................................... 63
Input Elements for getCustomerShippingAddressRequest................................................ 64
Input Elements for updateCustomerProfileRequest ............................................................ 65
Input Elements for updateCustomerPaymentProfileRequest............................................. 67
Input Elements for updateCustomerShippingAddressRequest ......................................... 73
Input Elements for validateCustomerPaymentProfileRequest ........................................... 76
Section 3........................................................................................... 78
Responses ........................................................................................ 78
CIM Responses ............................................................................................................. 78
Output for createCustomerProfileResponse ........................................................................ 79
Output for createCustomerPaymentProfileResponse ......................................................... 81
Last revised: 7/22/2009
Copyright © 1998 - 2007 Authorize.Net Corp. 3
Output for createCustomerShippingAddressResponse...................................................... 83
Output for createCustomerProfileTransactionResponse.................................................... 83
Output for deleteCustomerProfileResponse ........................................................................ 85
Output for deleteCustomerPaymentProfileResponse ......................................................... 85
Output for deleteCustomerShippingAddressResponse...................................................... 86
Output for getCustomerProfileIdsResponse ........................................................................ 87
Output for getCustomerProfileResponse ............................................................................. 87
Output for getCustomerPaymentProfileResponse .............................................................. 94
Output for getCustomerShippingAddressResponse........................................................... 98
Output for updateCustomerProfileResponse ..................................................................... 101
Output for updateCustomerPaymentProfileResponse...................................................... 101
Output for updateCustomerShippingAddressResponse .................................................. 102
Output for validateCustomerPaymentProfileResponse .................................................... 103
Duplicate Profile Verification ........................................................................................ 104
Response Codes ......................................................................................................... 105
Index............................................................................................... 107
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 4
Revision History
PUBLISH DATE
UPDATES
November 2007
Initial release of the Customer Information Manager (CIM) API
May 2008
Remove SecureSource requirements and various updates
January 2009
Addition of getCustomerProfileIdsRequest and various updates
July 2009
Clarified usage of validationMode for createCustomerProfileRequest calls when no payment profile information is included.
Added index.
Added note about optional fields and .NET programming
Corrected values for taxable variable.
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 5
Section 1
Developer Introduction
This guide describes the Web development required to create and manage customer profile information for the purpose of submitting transactions to the Authorize.Net Payment Gateway directly from a Web site or other application using extensible markup language (XML).
Specifically, the Authorize.Net Customer Information Manager (CIM) Application Programming Interface (API) provides a mechanism for developers and value added resellers (VARs) to create, delete, get, and update customer profile information, including payment and address information, via direct integration between client software or applications and the Authorize.Net Payment Gateway.
The CIM API accomplishes these functions through an XML call and subsequent XML response.
Minimum Requirements
Before you begin this integration for an Authorize.Net Payment Gateway account, please check with the merchant to make sure that the following minimum requirements have already been met.
• The merchant must have a U.S. based merchant bank account that allows Internet transactions.
• The merchant must have an active Authorize.Net Card Not Present Payment Gateway account.
• The merchant must be signed up for the CIM service.
• The merchant must store account authentication data securely (for example, API login ID, transaction key).
Note: Merchants should avoid storing any type of sensitive cardholder information. However, in the event that a merchant or third party must store sensitive customer business or payment information, compliance with industry standard storage requirements is required. Please see the Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf for guidelines.
Developer Support
There are several resources available to help you successfully integrate a merchant Web site or other application to the Authorize.Net Payment Gateway.
• The Integration Center at http://developer.authorize.net provides test accounts, sample code, FAQs, and troubleshooting tools.
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 6
• If you can’t find what you need in the Integration Center, our Integration Team is available to answer your questions via e-mail at integration@authorize.net.
• Be sure to read our Developer Security Best Practices White Paper at http://www.authorize.net/files/developerbestpractices.pdf for information on how to maximize the security and reliability of your merchant integration solutions.
If you have any suggestions about how we can improve or correct this guide, please e-mail documentation@authorize.net.
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 7
Section 2
Executing an API Call
The following sections describe the minimum requirements for executing an API call for managing customer profiles using XML.
There are two options for developing the request script:
• You may develop a custom script yourself using the API fields information provided in this document, OR
• You may use Authorize.Net sample code in C# and Java available for free from our Integration Center at http://developer.authorize.net/samplecode.
Note: If you choose to use Authorize.Net sample code, please be aware that in order to achieve a successful implementation it must be modified with developer test account or the merchant’s specific payment gateway account information.
Web Service Locations
ITEM
LOCATION
Production
https://api.authorize.net/xml/v1/request.api
Developer Test
https://apitest.authorize.net/xml/v1/request.api
XML Schema
https://api.authorize.net/xml/v1/schema/AnetApiSchema.xsd
In order to be processed successfully, API requests and responses must conform to the CIM API XML schema.
Note: The Developer Test URL requires the use of a developer test payment gateway account. You can request a test account from our Integration Center at http://developer.authorize.net/testaccount. Developer test accounts cannot be used to test against the Production URL.
Note for .NET programmers: When a parameter is optional, and if you use serialization, then the .NET language you are using automatically creates Boolean properties that indicate whether or not non-nullable parameters are specified. For example, if there is a parameter named validationMode that is an Enumeration type, a parameter called validationModeSpecified will automatically be created. By default, these properties are set to “false.”If a request passes a value for an optional parameter, be sure to set these properties to “true” so that the value is not ignored.
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 8
CIM Functions
The CIM API includes the following functions:
• createCustomerProfileRequest – Create a new customer profile along with any customer payment profiles and customer shipping addresses for the customer profile.
• createCustomerPaymentProfileRequest – Create a new customer payment profile for an existing customer profile. You can create up to 10 payment profiles for each customer profile.
• createCustomerShippingAddressRequest – Create a new customer shipping address for an existing customer profile. You can create up to 100 customer shipping addresses for each customer profile.
• createCustomerProfileTransactionRequest – Create a new payment transaction from an existing customer profile.
• deleteCustomerProfileRequest – Delete an existing customer profile along with all associated customer payment profiles and customer shipping addresses.
• deleteCustomerPaymentProfileRequest – Delete a customer payment profile from an existing customer profile.
• deleteCustomerShippingAddressRequest – Delete a customer shipping address from an existing customer profile.
• getCustomerProfileIdsRequest – Retrieve all customer profile IDs you have previously created.
• getCustomerProfileRequest – Retrieve an existing customer profile along with all the associated customer payment profiles and customer shipping addresses.
• getCustomerPaymentProfileRequest – Retrieve a customer payment profile for an existing customer profile.
• getCustomerShippingAddressRequest – Retrieve a customer shipping address for an existing customer profile.
• updateCustomerProfileRequest – Update an existing customer profile.
• updateCustomerPaymentProfileRequest – Update a customer payment profile for an existing customer profile.
• updateCustomerShippingAddressRequest – Update a shipping address for an existing customer profile.
• validateCustomerPaymentProfileRequest – Verify an existing customer payment profile by generating a test transaction.
The following sections provide information about the input elements required for executing the functions listed above. Indentations in the Element column indicate grouping hierarchy. All
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 9
elements are case sensitive and must be submitted in the order listed here. Elements are required unless otherwise indicated. Optional elements should not be submitted unless they contain valid values.
Note: Elements required for individual API calls are in addition to the authentication elements required for all API calls.
Authentication
ALL calls to the API require merchant authentication to ensure they originate from authorized sources. This implementation of the merchant Web services API supports authentication using the API Login ID and Transaction Key.
ELEMENT
VALUE
FORMAT
NOTES
merchantAuthentication
Contains merchant unique information for purposes of authentication
name
The valid API Login ID for the developer test or merchant account
Up to 25 characters
Submit the API Login ID used to submit transactions
transactionKey
The valid Transaction Key for the developer test or merchant account
16 characters
Submit the Transaction Key obtained from the Merchant Interface
Example of Authentication with the Login ID and Transaction Key
<?xml version="1.0" encoding="utf-8"?>
<createCustomerProfileRequest xmlns= "AnetApi/xml/v1/schema/AnetApiSchema.xsd">
<merchantAuthentication>
<name>mytestacct</name>
<transactionKey>112223344</transactionKey>
</merchantAuthentication>
</createCustomerProfileRequest>
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 10
Input Elements for createCustomerProfileRequest
This function is used to create a new customer profile along with any customer payment profiles and customer shipping addresses for the customer profile.
The following table lists the input elements for executing an API call to the createCustomerProfileRequest function.
ELEMENT
VALUE
FORMAT
NOTES
refId
Merchant-assigned reference ID for the request
Optional
Up to 20 characters
If included in the request, this value will be included in the response. This feature might be especially useful for multi-threaded applications.
profile
Contains information for the customer profile
At least one of the following fields must be submitted under profile: merchantCustomerId, description or email.
merchantCustomerId
Merchant assigned ID for the customer
Conditional
Up to 20 characters
Required only if no values for both description and email are submitted.
description
Description of the customer or customer profile
Conditional
Up to 255 characters
Required only if no values for both merchantCustomerId and email are submitted.
email
Email address associated with the customer profile
Conditional
Up to 255 characters
Required only if no values for both description and merchantCustomerId are submitted.
paymentProfiles
Contains payment profiles for the customer profile
Optional
Multiple instances of this element may be submitted to create multiple payment profiles for the customer profile.
customerType
Optional
individual
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 11
ELEMENT
VALUE
FORMAT
NOTES
business
billTo
firstName
The customer’s first name
Optional
Up to 50 characters (no symbols)
lastName
The customer’s last name
Optional
Up to 50 characters (no symbols)
company
The name of the company associated with the customer, if applicable
Optional
Up to 50 characters (no symbols)
address
The customer’s address
Optional
Up to 60 characters (no symbols)
city
The city of the customer’s address
Optional
Up to 40 characters (no symbols)
state
The state of the customer’s address
Optional
A valid two-character state code
zip
The ZIP code of the customer’s address
Optional
Up to 20 characters (no symbols)
country
The country of the customer’s
Up to 60 characters (no symbols)
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 12
ELEMENT
VALUE
FORMAT
NOTES
address
Optional
phoneNumber
The phone number associated with the customer profile
Optional
Up to 25 digits (no letters)
Ex. (123)123-1234
faxNumber
The fax number associated with the customer profile
Optional
Up to 25 digits (no letters)
Ex. (123)123-1234
payment
Contains payment profile information for the customer profile
Can contain creditCard or bankAccount
creditCard
Contains credit card payment information for the payment profile
This element is only required when the payment profile is credit card.
cardNumber
The customer’s credit card number
13 to 16 digits
expirationDate
The expiration date for the customer’s credit card
YYYY-MM
cardCode
The three- or four-digit number on the back of a credit card (on the front for American Express)
Optional
Numeric
This field is required if the merchant would like to use the Card Code Verification (CCV) security feature. For more information, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 13
ELEMENT
VALUE
FORMAT
NOTES
cardCode is only used for validation and will not be stored in the customer profile. It should only be used when submitting validationMode with a value of testMode or liveMode.
bankAccount
Contains bank account payment information for the payment profile
This element is only required when the payment profile is bank account.
accountType
The type of bank account for the payment profile
Optional
checking
savings
businessChecking
routingNumber
The routing number of the customer’s bank
9 digits
accountNumber
The customer’s bank account number
5 to 17 digits
nameOnAccount
The customer’s full name as listed on the bank account
Up to 22 characters
echeckType
The type of electronic check transaction
Optional
CCD
PPD
TEL
WEB
Currently, the CIM API does not support ARC or BOC transaction types.
bankName
The name of the bank associated with the bank account number
Optional
Up to 50 characters
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 14
ELEMENT
VALUE
FORMAT
NOTES
shipToList
Contains shipping address information for the customer profile
firstName
The customer’s first name
Optional
Up to 50 characters (no symbols)
lastName
The customer’s last name
Optional
Up to 50 characters (no symbols)
company
The name of the company associated with the customer, if applicable
Optional
Up to 50 characters (no symbols)
address
The customer’s shipping address
Optional
Up to 60 characters (no symbols)
city
The city of the customer’s shipping address
Optional
Up to 40 characters (no symbols)
state
The state of the customer’s shipping address
Optional
A valid two-character state code
zip
The ZIP code of the customer’s shipping address
Up to 20 characters (no symbols)
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 15
ELEMENT
VALUE
FORMAT
NOTES
Optional
country
The country of the customer’s shipping address
Optional
Up to 60 characters (no symbols)
phoneNumber
The phone number associated with the customer profile
Optional
Up to 25 digits (no letters)
Ex. (123)123-1234
faxNumber
The fax number associated with the customer profile
Optional
Up to 25 digits (no letters)
Ex. (123)123-1234
validationMode
Indicates the processing mode for the request
Optional
none
testMode
liveMode
Validation mode allows you to generate a test transaction at the time you create a customer profile. In Test Mode, only field validation is performed. In Live Mode, a transaction is generated and submitted to the processor with the amount of $0.01. If successful, the transaction is immediately voided. When a value of "none" is submitted, no additional validation is performed.
If a request does not include any payment profile information, the validation mode must be set to “none.”
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 16
ELEMENT
VALUE
FORMAT
NOTES
If a validation transaction is unsuccessful, the profile will not be created and the merchant will receive an error.
For information about output for this function, see the section of this document titled “Output Elements for createCustomerProfileResponse.”
Example createCustomerProfileRequest
<?xml version="1.0" encoding="utf-8"?>
<createCustomerProfileRequest xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
<merchantAuthentication>
<name>API Login ID here</name>
<transactionKey>Transaction Key here</transactionKey>
</merchantAuthentication>
<profile>
<merchantCustomerId>Merchant Customer ID here</merchantCustomerId>
<description>Profile description here</description>
<email>customer profile email address here</email>
<paymentProfiles>
<customerType>individual</customerType>
<payment>
<creditCard>
<cardNumber>Credit card number here</cardNumber>
<expirationDate>Credit card expiration date here</expirationDate>
</creditCard>
</payment>
</paymentProfiles>
</profile>
<validationMode>liveMode</validationMode>
</createCustomerProfileRequest>
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 17
Input Elements for createCustomerPaymentProfileRequest
This function is used to create a new customer payment profile for an existing customer profile.
The following table lists the input elements for executing an API call to the createCustomerPaymentProfileRequest function.
ELEMENT
VALUE
FORMAT
NOTES
refId
Merchant-assigned reference ID for the request
Optional
Up to 20 characters
If included in the request, this value will be included in the response. This feature might be especially useful for multi-threaded applications.
customerProfileId
Payment gateway assigned ID associated with the customer profile
Numeric
paymentProfile
Contains payment information for the customer profile
customerType
Optional
individual
business
billTo
firstName
The customer’s first name
Optional
Up to 50 characters (no symbols)
lastName
The customer’s last name
Optional
Up to 50 characters (no symbols)
company
The name of the company associated with the customer, if applicable
Optional
Up to 50 characters (no symbols)
address
The customer’s address
Up to 60 characters (no symbols)
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 18
ELEMENT
VALUE
FORMAT
NOTES
Optional
city
The city of the customer’s address
Optional
Up to 40 characters (no symbols)
state
The state of the customer’s address
Optional
A valid two-character state code
zip
The ZIP code of the customer’s address
Optional
Up to 20 characters (no symbols)
country
The country of the customer’s address
Optional
Up to 60 characters (no symbols)
phoneNumber
The phone number associated with the customer’s address
Optional
Up to 25 digits (no letters)
Ex. (123)123-1234
faxNumber
The fax number associated with the customer’s address
Optional
Up to 25 digits (no letters)
Ex. (123)123-1234
payment
Contains payment information for the customer profile
Can contain creditCard or bankAccount
creditCard
Contains credit card payment information for the customer profile
This element is only required when the payment profile is credit card.
cardNumber
The customer’s credit card number
13 to 16 digits
expirationDate
The expiration date for the customer’s
YYYY-MM
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 19
ELEMENT
VALUE
FORMAT
NOTES
credit card
cardCode
The three- or four-digit number on the back of a credit card (on the front for American Express)
Optional
Numeric
This field is required if the merchant would like to use the Card Code Verification (CCV) security feature. For more information, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.
cardCode is only used for validation and will not be stored in the customer profile. It should only be used when submitting validationMode with a value of testMode or liveMode.
bankAccount
Contains bank account payment information for the customer profile
This element is only required when the payment profile is bank account.
accountType
The type of bank account for the payment profile
Optional
checking
savings
businessChecking
routingNumber
The routing number of the customer’s bank
9 digits
accountNumber
The customer’s bank account number
5 to 17 digits
nameOnAccount
The customer’s full name as listed on the bank account
Up to 22 characters
echeckType
The type of electronic check transaction
Optional
CCD
PPD
TEL
WEB
Currently, the CIM API does not support ARC or BOC transaction types.
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 20
ELEMENT
VALUE
FORMAT
NOTES
bankName
The name of the bank associated with the bank account number
Optional
Up to 50 characters
validationMode
Indicates the processing mode for the request
none
testMode
liveMode
Validation mode allows you to generate a test transaction at the time you create a customer payment profile. In Test Mode, only field validation is performed. In Live Mode, a transaction is generated and submitted to the processor with the amount of $0.01. If successful, the transaction is immediately voided. When a value of "none" is submitted, no additional validation is performed.
For information about output elements for this function, see the section of this document titled “Output Elements for createCustomerPaymentProfileResponse.”
Example createCustomerPaymentProfileRequest
<?xml version="1.0" encoding="utf-8"?>
<createCustomerPaymentProfileRequest xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
<merchantAuthentication>
<name>YourUserLogin</name>
<transactionKey>YourTranKey</transactionKey>
</merchantAuthentication>
<customerProfileId>10000</customerProfileId>
<paymentProfile>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<company></company>
<address>123 Main St.</address>
<city>Bellevue</city>
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 21
<state>WA</state>
<zip>98004</zip>
<country>USA</country>
<phoneNumber>000-000-0000</phoneNumber>
<faxNumber></faxNumber>
</billTo>
<payment>
<creditCard>
<cardNumber>4111111111111111</cardNumber>
<expirationDate>2023-12</expirationDate>
</creditCard>
</payment>
</paymentProfile>
<validationMode>liveMode</validationMode>
</createCustomerPaymentProfileRequest>
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
Input Elements for createCustomerShippingAddressRequest
This function is used to create a new customer shipping address for an existing customer profile.
The following table lists the input elements for executing an API call to the createCustomerShippingAddressRequest function.
ELEMENT
VALUE
FORMAT
NOTES
refId
Merchant-assigned reference ID for the request
Optional
Up to 20 characters
If included in the request, this value will be included in the response. This feature might be especially useful for multi-threaded applications.
customerProfileId
Payment gateway assigned ID associated with the customer profile
Numeric
address
Contains shipping address information for the customer profile
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 22
ELEMENT
VALUE
FORMAT
NOTES
firstName
The customer’s first name
Optional
Up to 50 characters (no symbols)
lastName
The customer’s last name
Optional
Up to 50 characters (no symbols)
company
The name of the company associated with the customer, if applicable
Optional
Up to 50 characters (no symbols)
address
The customer’s shipping address
Optional
Up to 60 characters (no symbols)
city
The city of the customer’s shipping address
Optional
Up to 40 characters (no symbols)
state
The state of the customer’s shipping address
Optional
A valid two-character state code
zip
The ZIP code of the customer’s shipping address
Optional
Up to 20 characters (no symbols)
country
The country of the customer’s shipping address
Optional
Up to 60 characters (no symbols)
phoneNumber
The phone number associated with the customer’s shipping address
Up to 25 digits (no letters)
Ex. (123)123-1234
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 23
ELEMENT
VALUE
FORMAT
NOTES
Optional
faxNumber
The fax number associated with the customer’s shipping address
Optional
Up to 25 digits (no letters)
Ex. (123)123-1234
For information about output elements for this function, see the section of this document titled “Output Elements for createCustomerShippingAddressResponse.”
Example createCustomerShippingAddressRequest
<?xml version="1.0" encoding="utf-8"?>
<createCustomerShippingAddressRequest xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
<merchantAuthentication>
<name>YourUserLogin</name>
<transactionKey>YourTranKey</transactionKey>
</merchantAuthentication>
<customerProfileId>10000</customerProfileId>
<address>
<firstName>John</firstName>
<lastName>Doe</lastName>
<company></company>
<address>123 Main St.</address>
<city>Bellevue</city>
<state>WA</state>
<zip>98004</zip>
<country>USA</country>
<phoneNumber>000-000-0000</phoneNumber>
<faxNumber></faxNumber>
</address>
</createCustomerShippingAddressRequest>
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 24
Input Elements for createCustomerProfileTransactionRequest
This function is used to create a payment transaction from an existing customer profile. You can submit one of six transaction types: Authorization Only, Authorization and Capture, Capture Only, Prior Authorization and Capture, Refund and Void. For more information on these transaction types, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.
Note: The only transaction types that generate a customer receipt email are Authorization Only, Authorization and Capture, and Refund.
The following table lists the input elements for executing an API call to the createCustomerProfileTransactionRequest function for an Authorization Only transaction.
ELEMENT
VALUE
FORMAT
NOTES
refId
Merchant-assigned reference ID for the request
Optional
Up to 20 characters
If included in the request, this value will be included in the response. This feature might be especially useful for multi-threaded applications.
transaction
Contains transaction information
profileTransAuthOnly
The transaction type that is being requested
Only one transaction type is allowed per request.
amount
The total amount of the transaction
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount should include all other amounts such as tax amount, shipping amount, etc.
tax
Contains tax information for the transaction
Optional
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 25
ELEMENT
VALUE
FORMAT
NOTES
amount
The tax amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the tax for the transaction
Optional
Up to 31 characters
description
The tax description for the transaction
Optional
Up to 255 characters
shipping
Contains shipping information for the transaction
Optional
amount
The shipping amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the shipping for the transaction
Optional
Up to 31 characters
description
The shipping description for the transaction
Optional
Up to 255 characters
duty
Contains duty information for the transaction
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 26
ELEMENT
VALUE
FORMAT
NOTES
Optional
amount
The duty amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the duty for the transaction
Optional
Up to 31 characters
description
The duty description for the transaction
Optional
Up to 255 characters
lineItems
Contains line item details about the order
Optional
Up to 30 distinct instances of this element may be included per transaction to describe items included in the order.
itemId
The ID assigned to the item
Optional
Up to 31 characters
name
A short description of an item
Optional
Up to 31 characters
description
A detailed description of an item
Optional
Up to 255 characters
quantity
The quantity of an item
Up to 4 digits (up to two decimal places)
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 27
ELEMENT
VALUE
FORMAT
NOTES
Optional
unitPrice
Cost of an item per unit excluding tax, freight, and duty
Optional
Up to 4 digits with a decimal point (no dollar symbol)
Ex. 4.95
taxable
Indicates whether the item is subject to tax
Optional
false
true
customerProfileId
Payment gateway assigned ID associated with the customer profile
Numeric
customerPaymentProfileId
Payment gateway assigned ID associated with the customer payment profile
Numeric
customerShippingAddressId
Payment gateway assigned ID associated with the customer shipping address
Optional
Numeric
If customerShippingAddressId is not passed, shipping information will not be included with the transaction.
order
Contains information about the order
Optional
invoiceNumber
The merchant assigned invoice number for the
Up to 20 characters (no symbols)
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 28
ELEMENT
VALUE
FORMAT
NOTES
transaction
Optional
description
The transaction description
Optional
Up to 255 characters (no symbols)
purchaseOrderNumber
The merchant assigned purchase order number
Optional
Up to 25 characters (no symbols)
taxExempt
The tax exempt status
Optional
TRUE
FALSE
recurringBilling
The recurring billing status
Optional
TRUE
FALSE
cardCode
The customer’s card code (the three- or four-digit number on the back or front of a credit card)
Required only when the merchant would like to use the Card Code Verification (CCV) filter
Conditional
3 to 4 digits
This field is required if the merchant would like to use the CCV security feature. For more information, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.
extraOptions
Information in name/value pair format that does not exist within CIM,
String (see example below)
For a complete list of the transaction variable names available,
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 29
ELEMENT
VALUE
FORMAT
NOTES
such as customer IP address, etc.
Optional
please review the AIM Implementation Guide located at http://www.authorize.net/support/aim_guide.pdf.
For information about output elements for this function, see the section of this document titled “Output Elements for createCustomerProfileTransactionResponse.”
Example createCustomerProfileTransactionRequest for an Authorization Only transaction
<?xml version="1.0" encoding="utf-8"?>
<createCustomerProfileTransactionRequest xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
<merchantAuthentication>
<name>YourUserLogin</name>
<transactionKey>YourTranKey</transactionKey>
</merchantAuthentication>
<transaction>
<profileTransAuthOnly>
<amount>10.95</amount>
<tax>
<amount>1.00</amount>
<name>WA state sales tax</name>
<description>Washington state sales tax</description>
</tax>
<shipping>
<amount>2.00</amount>
<name>ground based shipping</name>
<description>Ground based 5 to 10 day shipping
</description>
</shipping>
<lineItems>
<itemId>ITEM00001</itemId>
<name>name of item sold</name>
<description>Description of item sold</description>
<quantity>1</quantity>
<unitPrice>6.95</unitPrice>
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 30
<taxable>true</taxable>
</lineItems>
<lineItems>
<itemId>ITEM00002</itemId>
<name>name of other item sold</name>
<description>Description of other item sold
</description>
<quantity>1</quantity>
<unitPrice>1.00</unitPrice>
<taxable>true</taxable>
</lineItems>
<customerProfileId>10000</customerProfileId>
<customerPaymentProfileId>20000</customerPaymentProfileId>
<customerShippingAddressId>30000</customerShippingAddressId>
<order>
<invoiceNumber>INV000001</invoiceNumber>
<description>description of transaction</description>
<purchaseOrderNumber>PONUM000001</purchaseOrderNumber>
</order>
<taxExempt>false</taxExempt>
<recurringBilling>false</recurringBilling>
<cardCode>000</cardCode>
</profileTransAuthOnly>
</transaction>
<extraOptions><![CDATA[x_customer_ip=100.0.0.1&x_authentication_indicator=5&x_cardholder_authentication_value=uq3wDbqt8A26rfANAAAAAP]]></extraOptions>
</createCustomerProfileTransactionRequest>
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
The following table lists the input elements for executing an API call to the createCustomerProfileTransactionRequest function for an Authorization and Capture transaction.
ELEMENT
VALUE
FORMAT
NOTES
refId
Merchant-assigned reference ID for
Up to 20 characters
If included in the request, this value will be
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 31
ELEMENT
VALUE
FORMAT
NOTES
the request
Optional
included in the response. This feature might be especially useful for multi-threaded applications.
transaction
Contains transaction information
profileTransAuthCapture
The transaction type that is being requested
Only one transaction type is allowed per request.
amount
The total amount of the transaction
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount should include all other amounts such as tax amount, shipping amount, etc.
tax
Contains tax information for the transaction
Optional
amount
The tax amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the tax for the transaction
Optional
Up to 31 characters
description
The tax description for the transaction
Optional
Up to 255 characters
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 32
ELEMENT
VALUE
FORMAT
NOTES
shipping
Contains shipping information for the transaction
Optional
amount
The shipping amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the shipping for the transaction
Optional
Up to 31 characters
description
The shipping description for the transaction
Optional
Up to 255 characters
duty
Contains duty information for the transaction
Optional
amount
The duty amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the duty for the transaction
Optional
Up to 31 characters
description
The duty description for the transaction
Up to 255 characters
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 33
ELEMENT
VALUE
FORMAT
NOTES
Optional
lineItems
Contains line item details about the order
Optional
Up to 30 distinct instances of this element may be included per transaction to describe items included in the order.
itemId
The ID assigned to the item
Optional
Up to 31 characters
name
A short description of an item
Optional
Up to 31 characters
description
A detailed description of an item
Optional
Up to 255 characters
quantity
The quantity of an item
Optional
Up to 4 digits (up to two decimal places)
unitPrice
Cost of an item per unit excluding tax, freight, and duty
Optional
Up to 4 digits with a decimal point (no dollar symbol)
Ex. 4.95
taxable
Indicates whether the item is subject to tax
Optional
false
true
customerProfileId
Payment
Numeric
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 34
ELEMENT
VALUE
FORMAT
NOTES
gateway assigned ID associated with the customer profile
customerPaymentProfileId
Payment gateway assigned ID associated with the customer payment profile
Numeric
customerShippingAddressId
Payment gateway assigned ID associated with the customer shipping address
Optional
Numeric
If customerShippingAddressId is not passed, shipping information will not be included with the transaction.
order
Contains information about the order
Optional
invoiceNumber
The merchant assigned invoice number for the transaction
Optional
Up to 20 characters (no symbols)
description
The transaction description
Optional
Up to 255 characters (no symbols)
purchaseOrderNumber
The merchant assigned purchase order number
Optional
Up to 25 characters (no symbols)
taxExempt
The tax exempt
TRUE
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 35
ELEMENT
VALUE
FORMAT
NOTES
status
Optional
FALSE
recurringBilling
The recurring billing status
Optional
TRUE
FALSE
cardCode
The customer’s card code (the three- or four-digit number on the back or front of a credit card)
Required only when the merchant would like to use the Card Code Verification (CCV) filter
Conditional
3 to 4 digits
This field is required if the merchant would like to use the CCV security feature. For more information, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/default.htm.
extraOptions
Information in name/value pair format that does not exist within CIM, such as customer IP address, etc.
Optional
String (see example below)
For a complete list of the transaction variable names available, please review the AIM Implementation Guide located at http://www.authorize.net/support/aim_guide.pdf.
For information about output elements for this function, see the section of this document titled “Output Elements for createCustomerProfileTransactionResponse.”
Example createCustomerProfileTransactionRequest for an Authorization and Capture transaction
<?xml version="1.0" encoding="utf-8"?>
<createCustomerProfileTransactionRequest xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 36
<merchantAuthentication>
<name>YourUserLogin</name>
<transactionKey>YourTranKey</transactionKey>
</merchantAuthentication>
<transaction>
<profileTransAuthCapture>
<amount>10.95</amount>
<tax>
<amount>1.00</amount>
<name>WA state sales tax</name>
<description>Washington state sales tax</description>
</tax>
<shipping>
<amount>2.00</amount>
<name>ground based shipping</name>
<description>Ground based 5 to 10 day shipping</description>
</shipping>
<lineItems>
<itemId>ITEM00001</itemId>
<name>name of item sold</name>
<description>Description of item sold</description>
<quantity>1</quantity>
<unitPrice>6.95</unitPrice>
<taxable>true</taxable>
</lineItems>
<lineItems>
<itemId>ITEM00002</itemId>
<name>name of other item sold</name>
<description>Description of other item sold</description>
<quantity>1</quantity>
<unitPrice>1.00</unitPrice>
<taxable>true</taxable>
</lineItems>
<customerProfileId>10000</customerProfileId>
<customerPaymentProfileId>20000</customerPaymentProfileId>
<customerShippingAddressId>30000</customerShippingAddressId>
<order>
<invoiceNumber>INV000001</invoiceNumber>
<description>description of transaction</description>
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 37
<purchaseOrderNumber>PONUM000001</purchaseOrderNumber>
</order>
<taxExempt>false</taxExempt>
<recurringBilling>false</recurringBilling>
<cardCode>000</cardCode>
</profileTransAuthCapture>
</transaction>
<extraOptions><![CDATA[x_customer_ip=100.0.0.1]]></extraOptions>
</createCustomerProfileTransactionRequest>
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
The following table lists the input elements for executing an API call to the createCustomerProfileTransactionRequest function for a Capture Only transaction.
ELEMENT
VALUE
FORMAT
NOTES
refId
Merchant-assigned reference ID for the request
Optional
Up to 20 characters
If included in the request, this value will be included in the response. This feature might be especially useful for multi-threaded applications.
transaction
Contains transaction information
profileTransCaptureOnly
The transaction type that is being requested
Only one transaction type is allowed per request.
amount
The total amount of the transaction
Up to 4 digits after the decimal point (no dollar symbol)
This amount should include all other amounts such as tax amount,
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 38
ELEMENT
VALUE
FORMAT
NOTES
Ex. 12.99 or 12.9999
shipping amount, etc.
tax
Contains tax information for the transaction
Optional
amount
The tax amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the tax for the transaction
Optional
Up to 31 characters
description
The tax description for the transaction
Optional
Up to 255 characters
shipping
Contains shipping information for the transaction
Optional
amount
The shipping amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the shipping for the transaction
Optional
Up to 31 characters
description
The shipping description for
Up to 255 characters
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 39
ELEMENT
VALUE
FORMAT
NOTES
the transaction
Optional
duty
Contains duty information for the transaction
Optional
amount
The duty amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the duty for the transaction
Optional
Up to 31 characters
description
The duty description for the transaction
Optional
Up to 255 characters
lineItems
Contains line item details about the order
Optional
Up to 30 distinct instances of this element may be included per transaction to describe items included in the order.
itemId
The ID assigned to the item
Optional
Up to 31 characters
name
A short description of an item
Optional
Up to 31 characters
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 40
ELEMENT
VALUE
FORMAT
NOTES
description
A detailed description of an item
Optional
Up to 255 characters
quantity
The quantity of an item
Optional
Up to 4 digits (up to two decimal places)
unitPrice
Cost of an item per unit excluding tax, freight, and duty
Optional
Up to 4 digits with a decimal point (no dollar symbol)
Ex. 4.95
taxable
Indicates whether the item is subject to tax
Optional
false
true
customerProfileId
Payment gateway assigned ID associated with the customer profile
Numeric
customerPaymentProfileId
Payment gateway assigned ID associated with the customer payment profile
Numeric
customerShippingAddressId
Payment gateway assigned ID associated with the customer shipping address
Optional
Numeric
If customerShippingAddressId is not passed, shipping information will not be included with the transaction.
order
Contains information
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 41
ELEMENT
VALUE
FORMAT
NOTES
about the order
Optional
invoiceNumber
The merchant assigned invoice number for the transaction
Optional
Up to 20 characters (no symbols)
description
The transaction description
Optional
Up to 255 characters (no symbols)
purchaseOrderNumber
The merchant assigned purchase order number
Optional
Up to 25 characters (no symbols)
taxExempt
The tax exempt status
Optional
TRUE
FALSE
recurringBilling
The recurring billing status
Optional
TRUE
FALSE
cardCode
The customer’s card code (the three- or four-digit number on the back or front of a credit card)
Required only when the merchant would like to use the Card Code Verification
3 to 4 digits
This field is required if the merchant would like to use the CCV security feature. For more information, please see the Merchant Integration Guide at http://www.authorize.net/support/Merchant/defa
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 42
ELEMENT
VALUE
FORMAT
NOTES
(CCV) filter
Conditional
ult.htm.
approvalCode
The authorization code of an original transaction required for a Capture Only
Conditional
6 characters
This element is only required for the Capture Only transaction type.
extraOptions
Information in name/value pair format that does not exist within CIM, such as customer IP address, etc.
Optional
String (see example below)
For a complete list of the transaction variable names available, please review the AIM Implementation Guide located at http://www.authorize.net/support/aim_guide.pdf.
For information about output elements for this function, see the section of this document titled “Output Elements for createCustomerProfileTransactionResponse.”
Example createCustomerProfileTransactionRequest for a Capture Only transaction
<?xml version="1.0" encoding="utf-8"?>
<createCustomerProfileTransactionRequest xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
<merchantAuthentication>
<name>YourUserLogin</name>
<transactionKey>YourTranKey</transactionKey>
</merchantAuthentication>
<transaction>
<profileTransCaptureOnly>
<amount>10.95</amount>
<tax>
<amount>1.00</amount>
<name>WA state sales tax</name>
<description>Washington state sales tax</description>
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 43
</tax>
<shipping>
<amount>2.00</amount>
<name>ground based shipping</name>
<description>Ground based 5 to 10 day shipping</description>
</shipping>
<lineItems>
<itemId>ITEM00001</itemId>
<name>name of item sold</name>
<description>Description of item sold</description>
<quantity>1</quantity>
<unitPrice>6.95</unitPrice>
<taxable>true</taxable>
</lineItems>
<lineItems>
<itemId>ITEM00002</itemId>
<name>name of other item sold</name>
<description>Description of other item sold</description>
<quantity>1</quantity>
<unitPrice>1.00</unitPrice>
<taxable>true</taxable>
</lineItems>
<customerProfileId>10000</customerProfileId>
<customerPaymentProfileId>20000</customerPaymentProfileId>
<customerShippingAddressId>30000</customerShippingAddressId>
<order>
<invoiceNumber>INV000001</invoiceNumber>
<description>description of transaction</description>
<purchaseOrderNumber>PONUM000001</purchaseOrderNumber>
</order>
<taxExempt>false</taxExempt>
<recurringBilling>false</recurringBilling>
<cardCode>000</cardCode>
<approvalCode>000000</approvalCode>
</profileTransCaptureOnly>
</transaction>
<extraOptions><![CDATA[x_customer_ip=100.0.0.1]]></extraOptions>
</createCustomerProfileTransactionRequest>
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 44
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
The following table lists the input elements for executing an API call to the createCustomerProfileTransactionRequest function for a Prior Authorization and Capture transaction.
ELEMENT
VALUE
FORMAT
NOTES
refId
Merchant-assigned reference ID for the request
Optional
Up to 20 characters
If included in the request, this value will be included in the response. This feature might be especially useful for multi-threaded applications.
transaction
Contains transaction information
profileTransPriorAuthCapture
The transaction type that is being requested
Only one transaction type is allowed per request.
amount
The total amount of the transaction
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount should include all other amounts such as tax amount, shipping amount, etc.
tax
Contains tax information for the transaction
Optional
Tax information from the original authorization transaction will be used if this field is not submitted.
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 45
ELEMENT
VALUE
FORMAT
NOTES
amount
The tax amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the tax for the transaction
Optional
Up to 31 characters
description
The tax description for the transaction
Optional
Up to 255 characters
shipping
Contains shipping information for the transaction
Optional
Shipping information from the original authorization transaction will be used if this field is not submitted.
amount
The shipping amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the shipping for the transaction
Optional
Up to 31 characters
description
The shipping description for the transaction
Optional
Up to 255 characters
duty
Contains duty information for the transaction
Duty information from the original authorization transaction will be used if this
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 46
ELEMENT
VALUE
FORMAT
NOTES
Optional
field is not submitted.
amount
The duty amount for the transaction
Optional
Up to 4 digits after the decimal point (no dollar symbol)
Ex. 12.99 or 12.9999
This amount must be included in the total amount for the transaction.
name
The name of the duty for the transaction
Optional
Up to 31 characters
description
The duty description for the transaction
Optional
Up to 255 characters
lineItems
Contains line item details about the order
Optional
Line item information from the original authorization transaction will be used if this field is not submitted.
Up to 30 distinct instances of this element may be included per transaction to describe items included in the order.
itemId
The ID assigned to the item
Optional
Up to 31 characters
name
A short description of an item
Up to 31 characters
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 47
ELEMENT
VALUE
FORMAT
NOTES
Optional
description
A detailed description of an item
Optional
Up to 255 characters
quantity
The quantity of an item
Optional
Up to 4 digits (up to two decimal places)
unitPrice
Cost of an item per unit excluding tax, freight, and duty
Optional
Up to 4 digits with a decimal point (no dollar symbol)
Ex. 4.95
taxable
Indicates whether the item is subject to tax
Optional
false
true
customerProfileId
Payment gateway assigned ID associated with the customer profile
Optional
Numeric
If a value is submitted for this field, it must be the same ID used for the original authorization transaction.
customerPaymentProfileId
Payment gateway assigned ID associated with the customer payment profile
Optional
Numeric
If a value is submitted for this field, it must be the same ID used for the original authorization transaction.
customerShippingAddressId
Payment gateway assigned ID associated with the customer
Numeric
If a value is submitted for this field, it must be the same ID used for the
Section 2 Executing an API Call
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 48
ELEMENT
VALUE
FORMAT
NOTES
shipping address
Optional
original authorization transaction.
transId
The payment gateway assigned transaction ID of the original transaction
Numeric
extraOptions
Information in name/value pair format that does not exist within CIM, such as customer IP address, etc.
Optional
String (see example below)
For a complete list of the transaction variable names available, please review the AIM Implementation Guide located at http://www.authorize.net/support/aim_guide.pdf.
For information about output elements for this function, see the section of this document titled “Output Elements for createCustomerProfileTransactionResponse.”
Example createCustomerProfileTransactionRequest for a Prior Authorization and Capture transaction
<?xml version="1.0" encoding="utf-8"?>
<createCustomerProfileTransactionRequest xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
<merchantAuthentication>
<name>YourUserLogin</name>
<transactionKey>YourTranKey</transactionKey>
</merchantAuthentication>
<transaction>
<profileTransPriorAuthCapture>
<amount>10.95</amount>
<tax>
<amount>1.00</amount>
<name>WA state sales tax</name>
<description>Washington state sales tax</description>
</tax>
Merchant Web Services API
Last revised: 7/22/2009
Copyright © 1998 - 2009 Authorize.Net, a CyberSource solution 49
<shipping>
<amount>2.00</amount>
<name>ground based shipping</name>
<description>Ground based 5 to 10 day shipping</description>
</shipping>
<lineItems>
<itemId>ITEM00001</itemId>
<name>name of item sold</name>
<description>Description of item sold</description>
<quantity>1</quantity>
<unitPrice>6.95</unitPrice>
<taxable>true</taxable>
</lineItems>
<lineItems>
<itemId>ITEM00002</itemId>
<name>name of other item sold</name>
<description>Description of other item sold</description>
<quantity>1</quantity>
<unitPrice>1.00</unitPrice>
<taxable>true</taxable>
</lineItems>
<customerProfileId>10000</customerProfileId>
<customerPaymentProfileId>20000</customerPaymentProfileId>
<customerShippingAddressId>30000</customerShippingAddressId>
<transId>40000</transId>
</profileTransPriorAuthCapture>
</transaction>
<extraOptions><![CDATA[]]></extraOptions>
</createCustomerProfileTransactionRequest>
Note: The sample code included in this document uses dummy field values. When using or testing sample code, be sure to enter valid field values. Additional sample code is available for download from the Authorize.Net Integration Center at http://developer.authorize.net/samplecode.
The following table lists the input elements for executing an API call to the createCustomerProfileTransactionRequest function for a Refund transaction.

Project Type I DO

Technology I Know

Web Technology

PHP FRAMEWORK

Symfony

Third Party Tools

Script Installtion

Tapestry Script

Payment Gateway

Database

Other Languages

Designing Tools

Previous Projects

I do lots of project click here to see more