Skip to loginSkip to content

Our API

Learn about Authorize.net APIs and Products

API documentation

Integrate with our APIs with easy to read documentation.

API reference

Easy no-setup way to test our APIs – Out of the box samples with editable body - Send requests to our sandbox and see responses.

Sample code on [GitHub]

Sample codes published on GitHub for each REST API in popular languages

SDKs on [GitHub]

SDKs source code published on GitHub in popular languages

API change log

Track changes to our APIs over the years

System change log

Track changes to our System over the years

Upgrade guide

Ready to upgrade your API integration? Here’s how :

Getting started

Time to make your first API call.

Get started

Step-by-step guide to make your first API call.

Common setup questions

Commonly-encountered problems and solutions.

How payments work

Curious about payments?

Testing guide

Complete your integration journey – guides with sandbox testing instructions and processor specific testing trigger data.

Go-Live checklist

A Handy checklist for to go-live

Support

Reach out to our award-winning customer support team, or contact sales directly.

Get support

Reach out to our award-winning customer support team, or contact sales directly.

News and announcements

Find what we’re building and what our customers are saying here.

Forums

Come discuss with our curated Developer Community

Authorize.net on GitHub

Easy access to Github

Authorize.net on Stack Overflow

StackOverflow posts

Developer blog

Read about how we build products & leverage technology at Authorize.net

Response (error) codes

A handy guide to all the error codes

FAQs

Frequently asked questions relating to Authorize.net REST APIs and developer center.

Knowledge base

Sandbox

Affiliate

Support

  • Accept Hosted
    • Requesting the Form Token
    • Get Hosted Payment Page Request and Response
    • Displaying the Form
    • Transaction Response
    • Error and Fraud Filter Handling

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.

The implementation and use of Accept Hosted follow a basic workflow:

1. You call getHostedPaymentPageRequest to request a form token. This request contains transaction information and form parameter settings.

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

3. Your customer completes and submits the payment form.

4. The API sends the transaction to Authorize.net for processing.

5. The customer is returned to your site, which displays a result page based on the URL followed or the response details sent.

Resources

  • Sample Accept Hosted Application on GitHub
  • API Reference
  • Looking for AIM/SIM?

Requesting the Form Token

The Accept Hosted process starts with a getHostedPaymentPageRequest API call. The response contains a form token that you can use in a subsequent request to display the hosted payment form. Using the form 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 form token is valid for 15 minutes. You must display the payment form within that time. If the browser makes a request for the payment form using an expired form token, an error is displayed.

The getHostedPaymentPageRequest call contains two primary elements:

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

Transaction Request 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.

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

Presenting Payment Options

You can present up to four payment options depending on which values you use in the hosted form parameters settings (explained in Hosted Form Parameter Settings below). Payment options include:

  • Payment Card - use the hostedPaymentPaymentOptions parameter.
  • eCheck (bank account) - use the hostedPaymentPaymentOptions parameter.
  • Customer Profile - use the hostedPaymentPaymentOptions parameter. See note below.

Important: 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 as shown in the image below. The customer can choose among these payment methods or enter new payment information, and save the new payment information in a payment profile that can be used in later transactions.

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 Get Hosted Payment Page Request and Response section below.

Important: The following parameter settings include options for marking form fields as required. However, the fields marked as required are not automatically required by Authorize.net.

To require fields on the hosted form:

  • 1. Log in to the Merchant Interface at https://login.authorize.net/ as an Account Administrator.
  • 2. Choose Account > Payment Form > Form Fields.
  • 3. Check Required for each field that you wish to require, or to disable the requirement.
  • 4. Click Submit.
Setting Name Parameters Description
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 is completed. The receipt page has a button labeled using the value of urlText. The button redirects the customer to the URL that you set with url. The urlText parameter defaults to Continue.

Use cancelUrlText to label a cancel button that redirects the customer to the URL that you set with 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. When there is no return URL, the receipt page is displayed by default.

Important: 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. The field defaults to #3F8FCD, a moderate shade of blue.
hostedPaymentPaymentOptions{"cardCodeRequired": false, "showCreditCard": true, "showBankAccount": true, "customerProfileId": false}

Use to control which payment options to display on the hosted payment form.

By default, cardCodeRequired and customerProfileId are false, and showCreditCard and showBankAccount are true.

To mark the card code field as required, set cardCodeRequired to true. See the Important note above for details on requiring fields.

To suppress payment 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. The field defaults to false.
hostedPaymentShippingAddressOptions{"show": false, "required": false}Use show to enable or disable the shipping address on the form. Use required to mark the shipping address as required. See the Important note above for details on requiring fields. Both show and required default to false.
hostedPaymentBillingAddressOptions{"show": true, "required": false}Use show to enable or disable the billing address on the form. The field defaults to true. Use required to mark the billing address as required. The field defaults to false. See the Important note above for details on requiring fields.
hostedPaymentCustomerOptions{"showEmail": false, "requiredEmail": false, "addPaymentProfile": true}

Use showEmail to enable or disable the email address on the form. Use requiredEmail to mark the email address as required. See the Important note above for details on requiring fields. 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 is sent with the form token request. The field defaults to true.

hostedPaymentOrderOptions{"show": true, "merchantName": "G and S Questions Inc."}Use show to enable or disable the display of merchantName on the hosted receipt page. The field defaults to true. Use merchantName to define how the merchant name appears on the receipt. If the showReceipt parameter in the hostedPaymentReturnOptions element is set to false, do not set merchantName.
hostedPaymentIFrameCommunicatorUrl{"url": "https://mysite.com/IFrameCommunicator.html"}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. Responses for successful transactions are returned through this mechanism. You must host the file on the same domain as the page in which you embedded the iframe popup window, and you must use HTTPS to encrypt the data sent to the iframe communicator URL. 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

Call the form by passing the form token that you received from the token element in the getHostedPaymentPageResponse API response.

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

  • Integrate the form using a redirect, in which case the payment form fills the full browser window.
  • Integrate the form using iframes, in which case the form pops up in a lightbox overlaid on your website.
  • Integrate the form using an embedded frame, in which case the payment form appears within your website.

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.

Important: There are Payment Form settings in the Authorize.net Merchant Interface that can cause transaction errors when unsent fields are marked as required.

To avoid errors caused by required fields:

  • 1. Log into the Merchant Interface at https://login.authorize.net/ as an Account Administrator.
  • 2. Choose Account > Payment Form > Form Fields.
  • 3. Choose Required for each field that you wish to require, or to disable the requirement.
  • 4. Click Submit.

Integrating the Form using a Redirect

Submit the form POST using the following 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 iframe communicator HTML file like the one shown below. The name of the file must match the hostedPaymentIFrameCommunicatorUrl setting name in your getHostedPaymentPageRequest API call. You must host the file on the same domain as the page in which you embedded the iframe popup window, and you must use HTTPS to encrypt the data sent to the iframe communicator URL.

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 token in an HTTP POST to Authorize.net, as shown below. The target should be the same as the iframe ID mentioned 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. You must host the file on the same domain as the page in which you embedded the iframe popup window, and you must use HTTPS to encrypt the data sent to the iframe communicator URL.

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.

Important: 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"}}

Important: 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 looks very much like a successful transaction; the held transaction has a transaction ID, but its status indicates 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 has 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 displays as normal, and the transaction appears 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:

Authorize.Net

Visa

Cybersource.com

Privacy

Ad prefernces

Cookie policy

Terms and conditions

© 2019-2022. Authorize.net. All rights reserved. All brand names and logos are the property of their respective owners, are used for identification purposes only, and do not imply product endorsement or affiliation with Authorize.net.

Open in a new window