Search Developer Site

Authenticating API Requests With OAuth 2.0

Before your application can access Authorize.Net merchant data or act on the merchant's behalf, it must be authenticated. To make this process as easy as possible, Authorize.Net provides the industry-standard OAuth 2.0 protocol for granting access.

Overview

The following diagram illustrates the process of receiving merchant permission, retrieving an authorization code, redirecting the merchant, and retrieving an access token.

1. The merchant visits your application, enters form information, and clicks a link or button to continue the process.

2. Your application redirects the merchant to Authorize.Net.

3. The merchant grants or denies to your application the permissions that you will provide when you register your application with Authorize.Net.

4. Authorize.Net returns an authorization code, contained in a redirect URL. This redirects the merchant back to your application.

5. Your application calls Authorize.Net and exchanges the authorization code for a token that can be used for authenticating transactions with Authorize.Net, as well as a refresh token that can used for additional calls.


Endpoint URLs

Sandbox: https://accesstest.authorize.net/oauth/v1/token

Production: https://access.authorize.net/oauth/v1/token

Registering Your Application

Before you can use OAuth credentials to connect to Authorize.Net on behalf of your merchant, you must register your application with us. You can register your application in the Authorize.Net Partner Interface. There are separate URLs for production and sandbox. For sandbox credentials, contact affiliate@authorize.net.

Production Partner Interface

Sandbox Partner Interface

To register your application:

Step 1. Log into the Partner Interface (see the production and sandbox URLs above), navigate to Partner Account, and click the Integrate tab.

Step 2. Click Add Application.

Enter the following information:

Text Field Information
Application NameName of the application for which you are requesting Oauth credentials.
DescriptionDescription of the application.
Redirect URLURL used to redirect the merchant to Authorize.Net so that they can log in with their credentials and authorize your application to perform certain actions on their behalf. See our OAuth API documentation page for more information.
ScopeSelect the permissions to give the application for the listed APIs, or for all listed APIs.

Step 3. Click Submit. Your application is registered and the Client ID and Client Secret are shown. Store them securely. You will need them to redirect the merchant, which is explained in the next section.

Click Done to return to the previous screen.

You can view your application in the Integrations page. Note that a Solution ID in shown in the right column of the Applications list. That Solution ID is now linked to your Client ID and will be audited automatically.

Redirecting the Merchant

When the merchant arrives at your site, you must redirect them to Authorize.Net so that they can log in with their credentials and authorize your application to perform certain actions on their behalf. Add a link to your site that contains the redirect URL that you supplied to Authorize.Net during registration, encoded with the following parameters as a query string:

Parameter Name Required Notes
client_idYesThis is the client ID appointed to your application by Authorize.Net during registration.
redirect_uriYesThis is the page that the merchant is redirected back to after granting you permissions. This must exactly match the redirect URL that you supplied during registration.
scopeYesSpecifies the level of access that the application is requesting.
  • Read-only permissions are for solutions that only need to read data and not create or update information on the merchant's behalf.
  • Read and write permissions allow all API calls for any enabled services, including generating transactions, ARB subscriptions, and CIM profiles.
stateNoThis value is echoed back in the response to protect against malicious interception, for example a CSRF attack.
subNoThe value must be oauth.

Sample URL for Obtaining an Authorization Code

https://account.authorize.net/oauth/authorize?sub=oauth&client_id=bjdk2V33pF&
state=someValue&scope=read,write&redirect_uri=https://www.yourredirecturl.com/

When the user initiates the redirect, the merchant is redirected to Authorize.Net, and if they are not already logged in, they will be prompted to do so. If the merchant's credentials are expired, they will be prompted to reset it, after which they must click the redirect link again. The interface page opens, stating the partner's name along with the permissions requested. The merchant is prompted to either Allow or Deny the request for permissions.

Merchants giving permissions to your application must log into their Merchant Interface as an Account Owner or Account Administrator. They must also generate an API Login ID and Transaction Key, if they haven't already.

When the merchant clicks Approve, Authorize.Net redirects them back to the URL that you defined in your redirect_uri parameter. Attached to the redirect_uri will be two important URL arguments that you need to read from the request:


Response Parameter Name Required Notes
codeYesThe code is the value that you will exchange with Authorize.Net for an access token in the next step of the authentication process. For security reasons, the authorization code has a ten minute lifespan and must be used before it expires; otherwise you must repeat all of the previous steps to request another.
stateYesA value used to test for possible CSRF attacks. This value is echoed back to you in the response from Authorize.Net. If the state values do not match, you could be the victim of a CSRF attack and you should throw an HTTP 401 error code in response.

Error Responses

Error Code Description
invalid_scopeThe requested scope is invalid, unknown, or malformed.
invalid_clientThe requested client_id is invalid, unknown, or malformed.
invalid_requestThe request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_clientThe client is not authorized to request an authorization code using this method.
invalid_redirect_uriThe requested redirectUri is invalid, unknown, or malformed.
client_not_foundThe requested client_id is not found in the system.
invalid_client_typeThe requested client_id is registered with invalid client type (only confidential clients are supported).

Retrieving the Access Token

Use the authorization code that you obtained in step 2 to retrieve an access token, which expires after one hour, and a refresh token, which expires after one year, from our /token REST endpoint.


Sample Token Request

Below is an exmple of a token request. While a header is not required, we recommend including the header v-c-client-correlation-id with a unique value, for every request to /token.

Token Request Parameters

Parameter Name Values Description
grant_typeauthorization_codeRequired. This determines what type of flow the Authorization Server will use to acquire user authorization.
codeThe authorization code received from the authorization server.Required. The value passed in this parameter must exactly match the value supplied by Oauth server during the authorization step.
client_idThe client ID obtained during client registration.Required. Indicates the client that is making the request.
client_secretThe client secret value obtained during client registration.Required. Provides additional security.

Sample Token Response

Error Responses

Error Code Description
access_deniedThe resource owner or authorization server denied the request.
server_errorThe authorization server encountered an unexpected condition that prevented it from fulfilling the request. This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client by an HTTP redirect.

Note: If you submit an expired token, you will receive a 401 error, as shown below.

Submitting API Requests

Use the access token to authenticate transactions. For requests to the Authorize.Net API, the access token is included in the merchantAuthentication block as shown in the following example:

In requests to the REST API, the access token is sent in an HTTP Authorization header with the Bearer type, as shown in the following example:

Authorization: Bearer eyJraWQiOiIyNmRjfjVkZTdlMmYwYTI0ODg0MjU1YjIwZWJjMGY0MSIsImFs

Error Responses

The following error is returned when the access token is invalid.

For more information about specific error responses when using the Authorize.Net API, see our Reason Response Code Tool.

Refreshing the Access Token

To refresh the token, send a POST to the /token endpoint that contains the following parameters:

Parameter Values Description
client_idThe client ID obtained during client registration.Required. Indicates the client that is making the request.
client_secretThe client secret value obtained during client registration.Required. Provides additional security.
grant_typerefresh_tokenRequired. This determines what type of token is created.
refresh_tokenThe value of the refresh token.Required. The value passed in this parameter must exactly match the refresh token value provided during the creation of the access token.

Sample Token-Refresh Request

Below is an exmple of a token refresh request. While a header is not required, we recommend including the header v-c-client-correlation-id with a unique value, for every request to /token.

Sample Token-Refresh Response

Error Responses

HTTP Status Code Error Error Description Notes
400invalid_requestThe request is missing a required parameter.Remove device_id.
400invalid_clientInvalid client .Returned if the client ID does not exist in our database.
400
400expired_clientClient status is expired.Client status is set to expired in the database.
400invalid_grantUnauthorized grant type.Returned if the client requests a grant type that is not supported by this client.
400invalid_grantLogin failure.Either username or merchant is not valid, password is incorrect, account is disabled, password is locked, or password is expired.
500server_errorUnable to create token.Generic server error.

Revoking Permissions

If the merchant revokes a solution's permissions in the Authorize.Net Merchant Interface, they will also revoke the refresh token immediately. Any previously issued access token will be valid till they expire. No new access token can be generated.

Boarding Integration

The OAuth boarding flows enable you to board a merchant and then do OAuth delegation for the newly boarded merchant during the same flow.

Two boarding flows are supported:

  • Landing page flow
  • MINT login flow

Landing Page Flow

By default, two pricing options are shown:

  • Payment gateway
  • Payment gateway with merchant account

To show only one pricing option, add a profileTypeID parameter to the URL and use a value of 1 to show pricing for payment gateway only, or 2 to show pricing for both merchant account and payment gateway.

Example URL with profileTypeID

https://account.authorize.net/signUpNow?resellerID=1234&profileTypeID=1&sub=oauth&client_id=bjdk2V33pF&state=someValue
&scope=read,write&redirect_uri=https://www.yourredirecturl.com/

NOTE: To use the testing environment, replace account.authorize.net with sandbox.authorize.net.

After the merchant accepts the pricing option, they are redirected to the OAuth page. Whether they accept or reject the OAuth delegation options, they are then redirected back to the partner site.

MINT Login Page Flow

The following sample URL shows how to redirect the customer to the MINT login page.

https://account.authorize.net/oauth/authorize?sub=oauth&client_id=xeQfpRRI5X&state=123456&scope=read%2cwrite
&redirect_uri=fhttps://www.yourredirecturl.com
&resellerId=3806&profileTypeId=2

NOTE: To use the testing environment, replace account.authorize.net with sandbox.authorize.net.

When the merchant clicks "Sign up now" they are shown pricing flows that depend on how you submitted profileTypeId. Add a profileTypeID parameter to the URL and use a value of 1 to show pricing for payment gateway only, or 2 to show pricing for both merchant account and payment gateway.

After the merchant accepts the pricing option, they are redirected to the OAuth page. Whether they accept or reject the OAuth delegation options, they are then redirected back to the partner site.

Setting the Merchant Account to Live Mode

When a merchant account is first created, it is set to Test mode by default. Before live transactions can be processed, the account must be set to live mode. You can do this by submitting updateMerchantDetailsRequest with isTestMode as shown below. Please note that while this call can usually be processed within moments of an account being created, certain circumstances may cause up to a 15 minute delay before it can be attempted.

Example isTestMode Request