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:
getHostedPaymentPageRequest to request a form token. This request contains transaction information and form parameter settings.
https://accept.authorize.net/payment/payment.
The Accept Hosted process starts with a getHostedPaymentPageRequest API call. The response contains a
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 |
|---|---|
| Required. Contains information about the transaction. |
| Required. Contains parameters that control the payment form for that transaction. |
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.
transactionRequest is absent or set to a NULL value.
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:
hostedPaymentPaymentOptions parameter.hostedPaymentPaymentOptions parameter.hostedPaymentPaymentOptions parameter. See note below.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.
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.
To require fields on the hosted form:
| 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 Use Use When
|
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, To mark the card code field as required, set To suppress payment card fields, set |
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 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 |
hostedPaymentCustomerOptions | {"showEmail": false, "requiredEmail": false, "addPaymentProfile": true} |
Use Use |
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. |
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:
https://test.authorize.net/payment/payment
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.
To avoid errors caused by required fields:
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:
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.
empty.html file:
The following code example shows all of the steps:
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.
The following code example shows all of the steps:
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.
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.
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 |
| Request Canceled | action=cancel |
When |
| Request Successful | action=transactResponse&response= ... |
When The JSON object might contain a |
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"}}
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.
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.
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.
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.
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: