Search Developer Site

Authorize.Net Accept Hosted

Authorize.Net Accept Hosted is a mobile-optimized payment form hosted by Authorize.Net that enables developers to use the Authorize.Net API to submit payment transactions, while maintaining SAQ-A level PCI compliance. Developers can redirect customers to the Authorize.Net payment form, or embed the Authorize.Net payment form directly in their own page. Our forms are mobile-optimized and designed to reduce friction in your customer experience. This next-generation solution replaces the previous hosted form, which used our legacy SIM API.

For Accept Hosted API reference information, see the API Reference Guide.

To use a JavaScript library to accept payments, either by integrating it into your payment form, or by using its included hosted form, see our documentation for Accept.js.


Step 1. Using our Authorize.Net API, call the API method getHostedPaymentPageRequest. The API response contains a form-validation token.

Step 2. Using the form-validation token returned in step 1, embed the payment form or redirect the customer to the payment form by sending an HTML form post to our URL -

Step 3. The customer fills in the payment form. The transaction is processed when the user submits the form. The customer returns to the merchant's site, and the merchant displays a result page based on the URL followed or the response information sent.

Requesting a Token

Every Accept Hosted transaction begins when your server sends us details of the transaction. Our server responds with a form token. You can use that token in a subsequent request that instructs our site display the payment form. The token is used to validate that the request for the payment form comes from you and that the payment amount or transaction details haven't been changed by the customer or a third party.

The token is valid for 15 minutes after receipt. The subsequent request to display the payment form must happen within that time. If the browser makes a request for the payment form using an expired token, an error will be displayed.

To request and receive a token, an application running on your server uses the Authorize.Net API to call the getHostedPaymentPageRequest method. This request contains two primary components:

  • transactionRequest - Required. Contains information about the transaction.

  • hostedPaymentSettings - Required. Contains parameters that control how the payment form is displayed and operates for that transaction.

The response to the API request contains the form-validation token that is then used by the browser request to display the form.

Transaction Information

The transactionRequest section of getHostedPaymentPageRequest contains information about the transaction and values that can be used to pre-populate the form fields. This section uses the same parameters and values as the transactionRequest element in the createTransactionRequest method of our API. Only the transactionType and amount elements are required.

Note: Only values which are non-empty and non-zero will be shown in the form.

If you're using our Customer Profiles feature to store customers’ payment information, you can send a customer's profile ID in the customerProfileId element of the token request. When the form is displayed in the browser, the 4 most recent payment profiles for that profile ID will be displayed. The customer can choose between these payment methods or choose to use a new payment method.

Hosted Form Parameter Settings

The following parameter settings are used with the getHostedPaymentPageRequest API method. All configuration options for how the form operates and displays are set by sending these parameters within hostedPaymentSettings in the token request. The form's appearance and behavior are not affected by SIM payment form settings or any other settings in the Merchant Interface.

Whether the API request is sent using JSON or XML formatting, the values for all parameters sent within hostedPaymentSettings are sent as JSON objects. If the API request is sent using JSON formatting, the values need to be sent using backslashes to escape the quote characters, as indicated in the sample transactions in the next section.

Setting Name Parameters Description/Validation
hostedPaymentReturnOptions{"showReceipt": true, "url": "", "urlText": "Continue", "cancelUrl": "", "cancelUrlText": "Cancel"}

All options associated with the return URLs, text, and behavior.

When embedded in an IFrame, the url, urlText, cancelUrl, and cancelUrlText parameters are optional.

When the showReceipt parameter is true, our system will display a receipt page after the transaction, with a "Continue" button that points back to the URL provided in the url parameter.

When showReceipt is false, a return URL must be provided in the url parameter. Otherwise the receipt page will be shown.

Important Note:

If the payment form is not embedded in an IFrame, the receipt page will be displayed and cannot be disabled, regardless of the value of showReceipt.

hostedPaymentButtonOptions{"text": "Pay"}Sets the text on the payment button.
hostedPaymentStyleOptions{"bgColor": "red"}Sets the accent color of the form. For example, the color of buttons and field lines. Default color, if not set, is blue (#3F8FCD). Acceptable values are CSS named values or RGB hex values.
hostedPaymentPaymentOptions{"cardCodeRequired": false, "showCreditCard": true, "showBankAccount": true}

Determines which payment options to display on the hosted payment form. By default, cardCodeRequired is false, and showCreditCard and showBankAccount are true.

To require Card Code Verification set cardCodeRequired to true.

To suppress credit card fields, set showCreditCard to false. To suppress bank account fields, set showBankAccount to false. Note that bank account fields will only appear if the merchant has added eCheck.Net to their payment gateway.

hostedPaymentSecurityOptions{"captcha": false}Determines whether CAPTCHA security is required on the form. The default is false.
hostedPaymentShippingAddressOptions{"show": false, "required": false}Determines whether shipping options will be shown on the form. Both parameters are false by default.
hostedPaymentBillingAddressOptions{"show": true, "required": false}Determines whether the billing address will be shown and/or required on the form. By default, they are shown but not required.
hostedPaymentCustomerOptions{"showEmail": false, "requiredEmail": false, "addPaymentProfile": true}

showEmail and requiredEmail determine whether the input field for the customer's email address will be shown and/or required on the form. Both parameters are false by default.

addPaymentProfile specifies whether to allow the customer to use the payment form to add a new form of payment to their customer profile. Applies when a customerProfileId has been sent with the token request. The default is true.

hostedPaymentOrderOptions{"show": true, "merchantName": "G and S Questions Inc."}

The value of the show field determines whether the merchant's name will be shown on the receipt page. The default is true.

merchantName is the name of the merchant.

hostedPaymentIFrameCommunicatorUrl{"url": ""}Enter the URL of 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. It is required only for IFrame or lightbox applications. Transaction response will be returned through this mechanism. For more information, see the Transaction Response section.

getHostedPaymentPageRequest() - Sample Request and Response

JSON Request

JSON Response

XML Request

XML Response

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 embed it as an IFrame into your existing page. You can use a light-box layout, in which the form pops up in front of the rest of your site, but not in a new window. Finally, you can use the full window by redirecting the browser to our form URL. Whatever method is used, the form is called by passing the received token to our system in an HTTP form POST. The only form field that must be included in that form is an input field named token. Insert the complete token that you've received back from getHostedPaymentPageRequest as the value of that field.




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.

Transaction Response

The payment form will automatically validate the input provided by the customer and give the customer the opportunity to change it before submitting the payment for processing. In the event of a payment decline or error, the customer remains on the form with the opportunity to revise their input and try again.

If the transaction processing is successful, the customer is presented with an optional receipt page, and a Continue button which returns control to the merchant’s site. Additionally, the customer may be presented with a Cancel button to return to the merchant’s site before the transaction is processed.

If the customer returns to the merchant’s site, the information passed to the merchant depends on the method used to integrate the form.

IFrame/Lightbox Method

For security reasons, web browsers do not allow JavaScript communication from a page inside an IFrame to the page that contains the IFrame if those pages are hosted on different domains. 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. When making the token request, you can pass us the URL for an IFrameCommunicator page. This IFrameCommunicator page is a small HTML page, hosted on your domain, and containing a JavaScript that listens for events. When you embed our hosted form in an IFrame on your page, our hosted form can in turn embed your IFrameCommunicator page within it inside an invisible IFrame. This enables a channel of communication that allows us to send messages to your IFrameCommunicator page. Then, as long as your IFrameCommunicator page is hosted on the same domain as your main page, it can communicate back to your main page.

This channel of communication is used to pass a few basic messages back to a listener script running on your main page (the page that calls the form):

  • Ideal height and width of the window - enables you to resize the frame and avoid any scrollbars from appearing.
  • Request Succeeded - returned when the transaction is completed at Authorize.Net. You can use this notification to know when to look for those changes through the Transaction Reporting API. Transaction response parameters (such as transaction ID) are returned with this notification.
  • Request Cancelled - returned when the customer cancels the hosted form.

Note: If you host our form in an IFrame, you must include the address to your IFrameCommunicator page in the hostedPaymentIFrameCommunicatorUrl parameter in the getHostedPaymentPageRequest method. To ensure you receive a response code, you must also set sendReceipt to false.

Note: You must use HTTPS in the URL to your IFrameCommunicator page.

For an example of an IFrameCommunicator page and more information about the messages passed, see our sample IFrameCommunicator.html in our sample application on GitHub.

Redirect Method

When not using an IFrame, the continue/return URL and cancel URL create buttons that when clicked cause the browser to perform a simple GET request to that URL. No other information about the transaction is provided directly. When using the redirect method, an Authorize.Net generated receipt will be shown and cannot be disabled.

All Methods

With any of the form integration methods, information specific to the customer can be passed back to the merchant’s server by embedding it in the continue/return URL or the cancel URL. By embedding information into the URL that is provided in the token request, the merchant server can identify the specific customer and transaction that has been processed when the customer returns. Any name-value pairs embedded in the URL should be URL-encoded to ensure correct processing in the form request.

Additionally, developers can register for Webhooks to receive real-time notifications when transactions are either declined or approved. Using Webhooks notifications, a developer would still be notified if a transaction was processed but the customer closed the browser before following the return URL.

Error Handling

Because this is a hosted payment form, processor card declines and other errors are handled within the form itself. For example, the image below shows a general processor decline (response code 2), simulated by passing the zip code 46282 in the Sandbox environment. The consumer can try another card or change field details. See the Sandbox Testing Guide for more details on simulating errors.

For declines caused by Advanced Fraud Detection Suite filters -- for example, when there is a billing address mismatch, using the test ZIP Code 46205 -- the form itself will handle the error notification and the consumer will be able to update their information and try again.

Held Transactions

A transaction held due to an Advanced Fraud Detection Suite filter will look very much like a successful transaction. The held transaction will have a transaction ID and perhaps an authorization code if the transaction was authorized before being held for review. The transaction will also have a Response Code of 4, indicating that it is being held for review. To learn more about handling held transactions using the API, see the Fraud Management API Reference.

If you are using the redirect method and the standard receipt page, a held transaction will not look any different to your customer.

If you are using an IFrame and if sendReceipt is set to false, you will be able to check the response code in the transactResponse iFrameUrlCommunicator message: