Search Developer Site

Accept Hosted

Accept Hosted is a mobile-optimized payment form hosted by Authorize.Net. It enables you to use the Authorize.Net API to submit payment transactions while maintaining SAQ-A level PCI compliance. You can redirect customers to the Accept Hosted payment form or embed the payment form directly in your own page.

For Accept Hosted API details, see the API Reference Guide.

To use a JavaScript library to accept payments, using either your payment form or the included hosted form, see the documentation for Accept.js.

Overview


1. You call getHostedPaymentPageRequest to request a form validation token.

2. You embed the payment form or redirect the customer to the payment form by sending an HTML POST containing the form validation token to https://accept.authorize.net/payment/payment.

3. Your customer completes and submits the payment form. The API sends the transaction to Authorize.Net for processing. The customer is returned to your site, which displays a result page based on the URL followed or the response details sent.

Requesting the Form Validation Token

The Accept Hosted process starts with a getHostedPaymentPageRequest API call. The response contains a form validation token that you can use in a subsequent request to display the hosted payment form. Using the token ensures that the payment form request comes from you and that the transaction details remain unchanged by the customer or a third party.

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

The getHostedPaymentPageRequest call contains two primary elements:

Setting Name Description/Validation
transactionRequestRequired. Contains information about the transaction.
hostedPaymentSettingsRequired. Contains parameters that control the payment form for that transaction.

Transaction Details

The transactionRequest element contains transaction details and values that can be used to populate the form fields. It uses the same child elements as the transactionRequest element in createTransactionRequest. Only the transactionType and amount elements are required.

Note: No form field is displayed if its corresponding element in transactionRequest is absent or set to a NULL value.

Presenting Payment Options

If you use the Customer Profiles feature to store customer payment information, you can send a customer profile ID in the customerProfileId element of the getHostedPaymentPageRequest call. When the browser displays the form, the four most recent payment profiles for that customer profile are displayed. The customer can choose among these payment methods or enter new payment information, and save the new payment information in a payment profile:

Hosted Form Parameter Settings

To control the payment form, use the following parameter settings within the hostedPaymentSettings element of the getHostedPaymentPageRequest API call.

The values for all parameters sent within hostedPaymentSettings are sent as JSON objects, regardless of whether you sent the getHostedPaymentPageRequest API call in JSON or XML format. If you send the API request in JSON format, use backslashes to escape the quote characters within hostedPaymentSettings, as shown in the next section.

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

Use these options to control the receipt page, return URLs, and buttons for both the payment form and the receipt page.

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

Use showReceipt to enable or disable the default receipt page after the transaction, with a continue button labeled using the value of urlText. The continue button redirects the customer to the URL set by url. The urlText parameter defaults to "Continue".

Use cancelUrlText to label a cancel button that redirects the customer to the URL set by cancelUrl. The button appears on the payment form and enables the customer to cancel the order and return to the merchant's site. The cancelUrlText parameter defaults to "Cancel".

When showReceipt is false, you must provide a return URL in the url parameter. If there is no return URL, the receipt page is displayed by default.

Note: If you do not embed the payment form in an iframe, the receipt page is displayed regardless of the value of showReceipt.

hostedPaymentButtonOptions{"text": "Pay"}Use to set the text on the payment button.
hostedPaymentStyleOptions{"bgColor": "red"}Use to set the accent color of the form, including button and field line colors. Acceptable values are CSS color keywords or RGB hexadecimal values. Defaults to #3F8FCD, a moderate shade of blue.
hostedPaymentPaymentOptions{"cardCodeRequired": false, "showCreditCard": true, "showBankAccount": true}

Use to control 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 the merchant must add eCheck.Net to their payment gateway to enable bank account fields on the payment form.

hostedPaymentSecurityOptions{"captcha": false}Use to enable or disable CAPTCHA security on the form. Defaults to false.
hostedPaymentShippingAddressOptions{"show": false, "required": false}Use show to enable or disable the shipping address on the form. Use required to require the shipping address. Both show and required default to false.
hostedPaymentBillingAddressOptions{"show": true, "required": false}Use show to enable or disable the billing address on the form. Defaults to true. Use required to require the billing address. Defaults to false.
hostedPaymentCustomerOptions{"showEmail": false, "requiredEmail": false, "addPaymentProfile": true}

Use showEmail to enable or disable the email address on the form. Use requiredEmail to require the email address. Both showEmail and requiredEmail default to false.

Use addPaymentProfile to enable the customer to add a new form of payment to their customer profile. Applies when a customerProfileId has been sent with the token request. Defaults to true.

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

Use show to enable or disable the display of merchantName. Defaults to true. Use merchantName to define how the merchant name appears on the payment form.

hostedPaymentIFrameCommunicatorUrl{"url": "https://mysite.com/special"}Use url to set the URL of a page that can communicate with the merchant's site using JavaScript. Required for iframe or lightbox applications. The transaction response is returned through this mechanism. For more information, see the Transaction Response section.

Get Hosted Payment Page Request and Response

JSON Request

JSON Response

XML Request

XML Response

Displaying the Form

You can integrate and display the Accept Hosted payment form into your site in three ways:

In all cases, you call the form by passing the form validation token obtained from the token element in the getHostedPaymentPageResponse API response.

Form POST URLs

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

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

See the sample application on GitHub to explore different ways to display the hosted form.

The payment form validates the customer field data and permits changes before the customer submits the data. In case of a payment decline or error, the customer remains on the form where they can make changes and try again. The customer can also click the cancel button, which displays the text submitted in the cancelUrlText parameter, and which returns the customer to the merchant page defined by cancelUrl.

If the transaction is processed successfully, and if you did not set showReceipt to false, a receipt page with a continue button is displayed. Use urlText to label the button. Upon clicking the button, the customer goes to the merchant page defined by url.

Note: Authorize.Net has Payment Form settings that do not currently affect field visibility in Accept Hosted but that might cause transaction errors because unsent fields are marked as required. To avoid errors caused by required fields, log in to the Merchant Interface as Account Administrator, navigate to Account > Settings > Transaction Format Settings > Payment Form > Form Fields, and uncheck Required for all fields. Note that if you use the deprecated SIM payment form, these settings will impact the fields that SIM requires.

Integrating the Form using a Redirect

Submit the form using the HTML parameter, action="https://test.authorize.net/payment/payment":

The following code example shows the individual steps together:

Integrating the Form Using Iframes and Lightboxes

Step 1. Create and host an HTML file like the one shown below. The name of the file must match the hostedPaymentIFrameCommunicatorUrl setting name in your getHostedPaymentPageRequest API call. Also, you should host the file on the same domain as the page where you embedded the iframe popup window.

Step 2. Create an empty.html file:

Step 3. Copy and paste the following HTML code snippet into the web page where you want your Accept Payment iframe popup. The HTML code snippet enables communication through the iframe communicator to Authorize.Net for window resizing and successful events. You might need to add a button to trigger the iframe communication.

Step 4. Submit the form validation token in an HTTP POST to Authorize.Net, as shown below. The target should be the same as the iframe ID mention in Step 3. The action attribute specifies the Accept Hosted payment page URL. Steps 3 and 4 together provide the Authorize.Net iframe popup in your web page, and you can customize the location.

Step 5. Add CSS styles to adjust the size and location of the Authorize.Net popup screen.

Step 6. Implement a method to receive the iframe communication response:

The following code example shows all of the steps:

Integrating an Embedded Iframe

Step 1. Create and host an HTML file like the one shown below. The name of the file must match the hostedPaymentIFrameCommunicatorUrl setting name in your getHostedPaymentPageRequest API call. Also, you should host the file on the same domain as the page in which you embedded the iframe popup window.

Step 2. Add an iframe place holder:

Step 3. Submit an HTTP POST:

Step 4. Implement a method to receive the iframe Communication response:

The following code example shows all of the steps:

Transaction Response

If the customer returns to the customer site, the merchant receives the results of the transaction. How the merchant receives the results depends on how you integrate the payment 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 the pages have different domains. Therefore, the hosted form cannot directly provide transaction details to the page that hosts the iframe.

However, by hosting on your domain a small JavaScript-powered page called an iframe communicator, you can pass some details between the payment form and the merchant site.

When you embed the hosted payment form in an iframe on your page, the form can in turn embed your iframe communicator within an invisible iframe. Through this invisible iframe, messages are sent to your iframe communicator. If you host the iframe communicator on the same domain as the page in which you embedded the form, the iframe communicator relays the messages to your page's listener script.

Note: You must use HTTPS in the URL to your iframe communicator.

Your iframe communicator can receive three types of messages:

Message Type Message Fields and Format Description/Validation
Resize Window action=resizeWindow&width=698&height=697

When action=resizeWindow, use the width and height parameters to resize your lightbox to the suggested payment form size.

Request Canceled action=cancel

When action=cancel, the customer canceled the payment form and redirected to the URL defined by the cancelUrl parameter that you sent in the getHostedPaymentPageRequest API call.

Request Successful action=transactResponse&response= ...

When action=transactionResponse, the response parameter contains a JSON object with the order details. See the JSON example for createTransactionResponse in the API Reference for details on the formatting of the JSON object.

The JSON object might contain a createPaymentProfileResponse property that indicates whether the customer successfully created a new payment profile.

The following example shows the iframe communicator message when the customer successfully submits a transaction through the embedded payment form. The createPaymentProfileResponse property appears only if the customer opts to save a new payment method, and if a new payment profile was successfully created, the success parameter is set to true.

action=transactResponse&response={"accountType":"MasterCard","accountNumber":"XXXX5454",
"transId":"2155590169","responseCode":"1","authorization":"D29J20","merchantName":
"G and S Questions Inc.","billTo":{"phoneNumber":"425 111 2222","firstName":"Bob",
"lastName":"Smith","address":"1234 Test Ave N.E. %5","city":"Tester","state":"WA","zip":
"98009","country":"USA"},"shipTo":{"firstName":"Bob","lastName":"Smith","address":
"1234 Test Ave N.E.","city":"Tester","state":"WA","zip":"98009","country":"USA"},
"orderDescription":"Order description","taxAmount":"1.01","shippingAmount":"2.01",
"dutyAmount":"3.01","customerId":"CUST12345","totalAmount":"62.88","poNumber":
"PO#12345678","orderInvoiceNumber":"INV_pf7JzZb","dateTime":"9/13/2018 5:40:55 PM",
"createPaymentProfileResponse":{"success":"true","message":"null"}}

Note: If you host the form in an iframe, you must include the iframe communicator URL in the hostedPaymentIFrameCommunicatorUrl parameter of your getHostedPaymentPageRequest API call. To ensure that you receive a response code, you must also set showReceipt to false.

We provide an example of an iframe communicator and more details about how it works in the sample application on GitHub.

Redirect Method

When you use the hosted payment form directly, rather than from within an iframe, the continue and cancel buttons send an HTTP GET request to that URL when clicked, and the customer is redirected to the cancel URL or continue URL, depending on which button the customer clicked. No other information about the transaction is provided. When you use the redirect method, the receipt page is always displayed.

All Methods

With any of the form integration methods, you can embed information specific to the customer into the continue URL or the cancel URL. The merchant server's code can embed a tracking code into the URL that can identify the specific customer and order details when the customer returns. URL-encode any name-value pairs embedded in the URL 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. A developer using Webhooks will receive a transaction notification regardless of whether the customer closed the browser without clicking the continue button.

Error and Fraud Filter Handling

Transaction declines and errors appear directly within the hosted payment form. For example, the image below shows a general decline (response code 2), which you can simulate in the sandbox environment by passing the ZIP code 46282. The customer can try another card or update other payment form fields to resolve the issue. See the Sandbox Testing Guide for more details on simulating errors.

For declines caused by the filters in the Advanced Fraud Detection Suite (AFDS), including Address Verification Service (AVS) filters, the form displays the error, and the customer can update the information and try again.

Held Transactions

When a transaction request triggers an AFDS filter set to hold transactions for review, the result will look very much like a successful transaction; the held transaction will have a transaction ID, but its status will indicate that it is held for review. The transaction might also have an authorization code if the merchant configured the AFDS filter to authorize the transaction before holding it for review. The transaction will have a Response Code of 4, indicating that the transaction is held for review. To learn more about handling held transactions using the API, see the Fraud Management section of the API Reference.

If you use the redirect method with the hosted receipt page, and a customer submits a transaction that is held for review, the receipt page will display as normal, and the transaction will appear to have processed successfully. The lack of errors or other indicators of a held review makes it harder to guess which conditions cause filtering and thus helps to reduce fraud.

If you use an iframe and showReceipt is set to false, you can check the response code in the transactResponse message sent to your iframe communicator: