Search Developer Site

Customer Profiles

You can use customer profiles to enable merchants to tokenize and store sensitive customer payment information on our secure servers, which simplifies PCI DSS compliance as well as the payments process for returning customers and recurring transactions. For Customer Profile API reference information, see the API Reference Guide.

By providing quick access to stored customer information, Customer Information Manager (CIM) is ideal for businesses that:

  • Process recurring transactions in which the date or amount or both are different each month; for example, utility companies.
  • Process usage charges that you bill only when the service is used; for example, pay-as-you-go cell phones.
  • Are concerned with PCI compliance.
  • Want to provide returning customers with the convenience of not having to re-enter personal data.

The Profiles API supports integration with a web site payment form or a proprietary business application. The profiles, which include payment and shipping information, can then be referenced in future transactions, eliminating steps in the transaction process for repeat customers and potentially increasing customer loyalty.

Customers

A customer profile contains minimal information about the customer such as ID, description, and email address, but its main purpose is to link multiple payment and shipping profiles with a single customer entity.

API methods to manage customer profiles include:

Payment Profiles

Payment profiles enable merchants to securely store sensitive payment information with Authorize.Net in a secure and PCI-compliant manner.

API methods to manage customer payment profiles include:

Shipping Profiles

Shipping profiles enable merchants to expedite the checkout process for repeat customers by securely storing multiple shipping addresses with Authorize.Net.

API methods to manage customer payment profiles include:

Duplicate Profile Verification

The duplicate profile verification prevents accidental duplicate submissions. When you submit calls to the createCustomerProfileRequest, createCustomerPaymentProfileRequest, and createCustomerShippingAddressRequest functions, the payment gateway checks certain fields in each request to ensure that a profile with the same information does not already exist. If the payment gateway finds a matching profile, it returns an error message. If the duplicate profile is a customer profile, the error message contains the ID of the existing profile. The following table lists the fields for each function that cannot match an existing profile. An error occurs only when all of the values for each field being submitted match all of the values for each field in the existing profile.

Function Fields Used for Duplicate Profile Verification
createCustomerProfileRequest
  • merchantCustomerId
  • description
  • email
createCustomerPaymentProfileRequest
  • customerProfileId
  • cardNumber
  • accountNumber
  • routingNumber
  • billToFirstName
  • billToLastName
  • billToAddress
  • billToZip
createCustomerShippingAddressRequest
  • customerProfileId
  • firstName
  • lastName
  • address
  • address
  • zip
  • phoneNumber

Using the Accept Customer Hosted Form

Authorize.Net Accept Customer is a fully hosted solution for payment information capture which allows developers to leverage our Customer Profiles API while still maintaining SAQ-A level PCI compliance. Our forms are mobile-optimized and designed to reduce friction in your consumer experience.

Identifying the Customer

Before you can present the hosted form, you need a way of identifying returning customers. You can have the customer log in to your site. Several content management systems and shopping carts automatically support that functionality. It is important that the login process is reliable so that one customer does not have access to another's stored payment information.

For first-time customers, you must create a new profile using the createCustomerProfileRequest method.

A customer profile contains any unique combination:

  • Customer ID (any value you choose)
  • Email
  • Description

Once the profile is created, you'll receive a unique profile ID that you can use to identify this customer in the future.

Retrieving a Token

Before you can send the HTML form post, you will need to retrieve a token using the getHostedProfilePageRequest method.

You must include the Customer's profile ID in your request.

See the section Guidelines for Parameter Settings for more information on configuring parameter settings for the hosted form.

Presenting the Hosted Form

The token is passed in a basic HTML form with the input name "token". The input name "token" is the only input value that must be included for a request to add a new payment or shipping profile, or to manage all of your profiles in one window. To prompt the customer to edit only a single existing profile, then you must include the associated profile ID in an additional "paymentProfileId" or "shippingAddressId" form POST field.

The type of form that you display is determined by the URL that the form is submitted to, also known as the form action, shown below:

Form Action URLs

Conditional Fields

  • To edit the payment profile, include paymentProfileId
  • To edit the shipping address include shppingAddressId

<form method="post" action="https://test.authorize.net/customer/editPayment"> <input type="hidden" name="token" value="HOSTED_PAGE_TOKEN"/> <input type="text" name="paymentProfileId" value="PROFILE_ID_TO_EDIT"/> ... </form>

Sandbox

To test in sandbox substitute "test" for "accept" in the form URL. E.g.

Displaying the Form

The hosted form is designed so that you have the freedom to integrate it into your site in almost any way. You can configure it as a separate pop-up window or embed it into your existing site. You can use a "lightbox" layout, in which the box pops up in front of the rest of your site, but not in a new window. Finally, you can just use the full window by directing the customer to Authorize.Net and letting them direct themselves back again, which avoids the use of Javascript.

Our sample application on github shows examples of how to present the form in different modes, including examples of how to open the hosted form in a lightbox. The lightbox layout can also be accomplished with third-party Javascript toolkits such as jquery.

Redirect

To implement hosted CIM access by using a redirect to Authorize.Net, follow these steps:

Step 1 - When you receive the token returned by the GetHostedProfilePageResponse function call, put a hidden form somewhere on your page (the value for the token will be the value returned by the function call).

If you are using the test environment, replace secure.authorize.net/profile/manage with test.authorize.net/profile/manage.

<form method="post" action="https://secure.authorize.net/profile/manage">

<input type="hidden" name="token" value="pfGaUNntEKMGfyWPmI4p+Bb4TJf2F0NCoCBp3cOXB7"/>

<input type="submit" value="Manage my payment and shipping information"/>

</form>

Step 2 - Add a button on your page that redirects the customer to Authorize.Net's secure site. You can customize the text:

<input type="button" onclick= "document.getElementById( 'formAuthorizeNetPage').submit();">Manage my payment and shipping information</input>

In this example, the Manage my payment and shipping information button directs users to the Authorize.Net Customer Information Manager Hosted page, where they can:

  • Create a new payment profile
  • Update or delete current credit card or bank information
  • Enter a new shipping address
  • Update or delete current shipping address

iFrame

For security reasons, web browsers do not allow Javascript communication between two pages that are hosted on different domains, even if one is embedded within another. Therefore, our hosted form cannot directly provide information to the page that is encapsulating it.

However, it is beneficial to provide some small amount of information indirectly through a third page. You can embed our hosted form in an iFrame, which enables us to embed your iFrameCommunicator inside our hosted form. This channel of communication allows us to send messages to your iFrameCommunicator page. As long as your communicator page is hosted on the same domain as your main page, it can to communicate

This channel of communication is used to pass a few basic messages to your site:

  • Ideal height and width of the window--allows you to resize the frame and avoid any scrollbars from appearing.
  • Changes Saved--returned whenever the customer saves changes to their profile. You can use this notification to know when to look for those changes through the CIM API.
  • Request Cancelled--returned when the merchant backs out of the hosted form.

NOTE: You must use https when using iFrameCommunicator.

Guidelines for Parameter Setting

The following parameter settings are used with the getHostedProfilePageRequest field.

To integrate to the hosted page as a redirect, pass the hostedProfileReturnUrl parameter and the hostedProfileReturnUrlText parameter. The parameter hostedProfilePageBorderVisible=true is optional.

To integrate to the hosted page as a popup, pass the hostedProfilePageBorderVisible=false parameter and the hostedProfileIFrameCommunicatorUrl parameter.

The following table shows possible settings:

Parameter

Description

hostedProfileReturnUrl

Enter the URL for the page that the customer returns to when the hosted session ends. Do not pass this setting for iframes or popups.

The return URL is validated to verify that it begins with http:// or https://

hostedProfileReturnUrlText

Enter the text to display on the button that returns the customer to your web site. The value can be any text up to 200 characters. If you do not pass this parameter, the default button text is Continue. Do not pass this setting for iframes or popups.

hostedProfileReturnUrlText

Enter the text to display on the button that returns the customer to your web site. The value can be any text up to 200 characters. If you do not pass this parameter, the default button text is Continue. Do not pass this setting for iframes or popups.

hostedProfilePageBorderVisible

Enter true or false. Must be false for iframes or popups, and must be true for redirects

hostedProfileHeadingBgColor

Enter a hex color string such as #e0e0e0. The background color of the section headers changes from gray to a custom color.

hostedProfileIFrameCommunicatorUrl

Enter the URL to a page that can communicate with the merchant's main page using javascript. This parameter enables you to dynamically change the size of the popup so that there are no scroll bars. This parameter is required only for iframe or lightbox applications.

hostedProfileValidationMode

liveMode--this value is the default setting. liveMode generates a transaction to the processor in the amount of 0.01 or 0.00. If successful, the transaction is immediately voided. Visa authorization transactions are changing from 0.01 to 0.00 for all processors. All other credit card types use 0.01.

Standard gateway and merchant account fees may apply to the authorization transactions. For Visa transactions using 0.00, the billTo address and billTo zip fields are required.

testMode--performs field validation only. All fields are validated. However, fields with unrestricted field definitions (such as telephone number) do not generate errors.

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

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

hostedProfileBillingAddressRequired

Format: Boolean; default is false.

Notes: When set to true, results in an asterisk next to the required fields on the hosted form. Sets First Name, Last Name, Address, City, State, and Zip Code as required fields in order for a payment profile to be created or updated within a hosted CIM form.

hostedProfileCardCodeRequired

Format: Boolean. Default is false.

Notes: When set to true, sets the Card Code field as required in order for a payment profile to be created or updated within a hosted CIM form. Results in an asterisk next to the card code field on the hosted form.

hostedProfileBillingAddressOptions

Format: Enum (showBillingAddress/showNone). Default is showBillingAddress. Applicable to Add/Edit Payment Pages. When set to showBillingAddress, all billing address fields including name fields will be shown. When set to showNone, no billing address fields will be shown, only payment method fields.

hostedProfileManageOptions

Format: Enum (showAll/showPayment/showShipping). Default is showAll. Applicable to Manage pages. When set to showAll, both Payment and Shipping sections will be shown. When set to showPayment, only Manage Payment section will be shown. When set to showShipping, only Manage Shipping section will be shown.

Charging Customer Profiles

Charging a Profile Using the createtransactionRequest Function

You can use profile information in the payment element of a createTransactionRequest function.

Refunds

If you are submitting a refund against a previous CIM transaction, the following guidelines apply:

  • Include customerProfileId, customerPaymentProfileId, and transId.
  • customerShippingAddressId is optional.
  • creditCardNumberMasked, bankRoutingNumberMasked, and bankAccountNumberMasked do not need to be included, but they are validated if they are included.

If you are submitting a refund for a non-CIM transaction, the following guidelines apply:

  • You must include transId, creditCardNumberMasked (or bankRoutingNumberMasked and bankAccountNumberMasked).
  • Do not include customerProfileId, customerPaymentProfileId, or customerShippingAddressId.

You can also issue an unlinked refund for a CIM transaction. In this case, the following rules apply:

  • You must be enrolled in Expanded Credit Capabilities (ECC). For more information about ECC, go to http://www.authorize.net/files/ecc.pdf.
  • You must include customerProfileId and customerPaymentProfileId.
  • customerShippingAddressId is optional.
  • Do not include transId, creditCardNumberMasked, bankRoutingNumberMasked, or bankAccountNumberMasked.