Search Developer Site

Authorize.Net Accept Hosted

Authorize.Net Accept Hosted is a 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.

Authorize.Net Signature Key

Authorize.Net uses your unique merchant signature key (the signature key is separate from the transaction key) to make sure the amount cannot be altered at any point in the transaction flow. You can generate a signature key at our merchant interface at Account > Settings > General Settings > Security Settings > API Credentials and Keys. Signature Key Last Obtained must be populated. If it is not, go to the Create New Key(s) section and generate a new key.

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 invalid token 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: "This request was cancelled."}

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

When embedded in an IFrame, the value of the showReceipt field determines whether the receipt page is shown. If the value of the showReceipt field is false, a return URL must be provided in the "url" parameter. Otherwise the receipt page will be shown.

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.