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.

Overview

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 - https://accept.authorize.net/payment/payment.

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 with your server send us details of the transaction you'd like to perform and receiving a form token in response. That token is used in a subsequent request by the customer's browser, which will request our site to 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 needs to 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 our Authorize.Net API to call the API method getHostedPaymentPageRequest. This request contains two primary components:

  • transactionRequest - contains information about the transaction.

  • hostedPaymentSettings - 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 Settings

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.

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.

Setting Name Parameters Description/Validation
hostedPaymentReturnOptions {"showReceipt" : true, "url":"https://mysite.com/receipt", "urlText": "Continue", "cancelUrl": "https://mysite.com/cancel", "cancelUrlText": "Cancel"}

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

When redirecting the browser to a payment form, the value of the showReceipt parameter determines whether an Authorize.Net receipt page is shown after completion of the transaction. If 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. If the value of the showReceipt parameter is false, the browser will return directly to the return URL. When showReceipt is false, a return URL must be provided in the url parameter. Otherwise the receipt page will be shown.

When embedded in an IFrame, the value of the showReceipt parameter determines whether an Authorize.Net receipt page is shown in the IFrame after the transaction. The url and cancelUrl parameters are optional in this scenario.

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": true} Determines whether the card code is a required field on the form. The default is false.
hostedPaymentSecurityOptions {"captcha": true} Determines whether CAPTCHA security is required on the form. The default is false.
hostedPaymentShippingAddressOptions {"show": true, "required":true} Determines whether shipping options will be shown on the form. Both parameters are false by default.
hostedPaymentBillingAddressOptions {"show": true, "required":true} 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} Determines 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.
hostedPaymentOrderOptions {"show": true, "merchantName": "G and S Questions Inc."}

The value of the show field determines whether the merchant's name will be shown. It is true by default.

merchantName is the name of the merchant.

hostedPaymentIFrameCommunicatorUrl {"url": "https://mysite.com/special"} 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 section "Transaction Response", below.

GetHostedPaymentForm() - 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.

Form POST URLs:

Sandbox: https://test.authorize.net/payment/payment

Production: https://accept.authorize.net/payment/payment

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 provide 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 optionally 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 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 encapsulates 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 page 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 communicate with your main page.

This channel of communication is used to pass a few basic messages to a listener script running on your 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. Transaction response parameters (such as transaction ID) are returned.
  • Request Cancelled - returned when the merchant cancels the hosted form.

Note: If you plan to use IFrame, you must send the hostedPaymentIFrameCommunicatorUrl parameter in the getHostedPaymentPageRequest method.

Note: You must use HTTPS when using IFrameCommunicator.

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 (see Sandbox Testing Guide for more details on simulating errors). The consumer can try another card or change field details.

For AFDS Declines (for example when there is a billing address mismatch – using the test zip 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 held transaction(soft decline – response code 4) will look very much like a successful transaction; it will have a transaction ID and perhaps an authorization code if the transaction was authorized before being held for review. The difference is that the response code for a held transaction will be 4 rather than 1.

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 you will be able to check the response code in the transactResponse iFrameUrlCommunicator message: