Authorize.net API Documentation - Authenticating API Requests With OAuth 2.0

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.

Resources

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 [email protected].

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 Name`	Name of the application for which you are requesting OAuth credentials.
`Description`	Description of the application.
`Redirect URL`	This 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.
`Scope`	Select 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_id`	Yes	This is the client ID appointed to your application by Authorize.net during registration.
`redirect_uri`	Yes	This 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.
`scope`	Yes	Specifies 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.
`state`	No	This value is echoed back in the response to protect against malicious interception, for example a CSRF attack.
`sub`	No	The 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
`code`	Yes	The 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.
`state`	Yes	A 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_scope`	The requested scope is invalid, unknown, or malformed.
`invalid_client`	The requested `client_id` is invalid, unknown, or malformed.
`invalid_request`	The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
`unauthorized_client`	The client is not authorized to request an authorization code using this method.
`invalid_redirect_uri`	The requested `redirectUri` is invalid, unknown, or malformed.
`client_not_found`	The requested `client_id` is not found in the system.
`invalid_client_type`	The 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 example 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.

POST https://access.authorize.net/oauth/v1/token
Content-Type: application/x-www-form-urlencoded


grant_type=authorization_code&code=sg#thsu67&client_id=o2client&client_secret=67868687&platform=2

Token Request Parameters

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

Sample Token Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiI0Y2E5NGUyNy04NzkzLTRmOGQtYjY4YS01OWM0MjMwODlhZDAiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDE5NjM0MiwiY2xpZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODk5NjM0Mn0.cmYor7iW6lxRCiM3kWPKauMsiKNGwRrrRFKowcTdkRQewgbQ0Mn9As1RhZwDKL4duxCzAzLw4e8aV8PUyd2-_eCUsqbPMWLWjGo75eU8GI9rrvSGTxEP-fr6jPAr-jBJekQTzMLgkKVtSGaJgtz08dHqrJnrejR8rZs4h1GpPMk6i99cOVMHjuTV7ZzognvkLKj_OR01H4XK5M8TWH5uoAXWrII3K-JJV1YkzjpVkpS0tVXTIXJI-pk_eNeBaJ7Q6in9X3xQKXnIqA8I8zxZt3LNnxR-aui2yufzP5BDh2kfwU0B1Uq8fEuqNmbj4HN1NrmnTHkRJTZ4ooYoqAQtnQ",
  "token_type": "bearer",
  "refresh_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiI4N2IxNDg2MC03YzI0LTQ0NmQtOWJlYS05Mzk2ZDI3MmNmOWQiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDE5NjMyMywiY2xeZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODk5NjMyM30.Fn8ZlXgvGBr-uvDi6e7-72g8tP-u42T5FNW5NW4YQ7GkrMqUEthexGc9NOcf6uWYfSD4EiSbDVO8EIojZzIUgyXmG3tYDgSejFcDSPcMrF11m9WkOcapbIFTnFk2OyPVi48BVZ6vNb7j2184pJ3KHKoq9E7qlaKrEbvBn2HRVdtvb1yj1Xv1tH38I6Qong8xMAEMCcIfzTinEOFIbENYzgxBsSNVrS15CYtDRFEDPGmAVPzd4I7HN_ed-pzOET3YbUBBQUbrAuZSrSrBcgfBCtT9C5szd7tYXmi-1AMVdFybnVXArAXsDX0nZzm-PuCi_DGKMJET0sY2QNyesyKv8w",
  "expires_in": 28798,
  "scope": "read write",
  "refresh_token_expires_in": 28799,
  "client_status": "active"
}

Error Responses

Error Code	Description
`access_denied`	The resource owner or authorization server denied the request.
`server_error`	The 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.

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

{
  "status": 401,
  "reason": "ACCESS_TOKEN_EXPIRED",
  "message": "The provided access token has expired",
  "correlationId": "a14f7c31-a0dc-4dd7-a2a6-8ddba2c84059"
}

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:

{
	"authenticateTestRequest": {
		"merchantAuthentication": {
			"accessToken": "eyJraWQiOiIyNmRjfjVkZTdlMmYwYTI0ODg0MjU1YjIwZWJjMGY0MSIsImFs
		}
	}
}

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.

<?xml version="1.0" encoding="UTF-8"?>
<updateMerchantDetailsResponse xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <messages>
	  <resultCode>Error</resultCode>
	  <message>
		 <code>E00124</code>
		 <text>The provided access token is invalid</text>
	  </message>
   </messages>
</updateMerchantDetailsResponse>

For more information about specific error responses when using the Authorize.net API, see our 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_id`	The client ID obtained during client registration.	Required. Indicates the client that is making the request.
`client_secret`	The client secret value obtained during client registration.	Required. Provides additional security.
`grant_type`	refresh_token	Required. This determines what type of token is created.
`refresh_token`	The 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 example 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.

POST https://access.authorize.net/oauth/v1/token
Content-Type: application/x-www-form-urlencoded
 
client_id=8l57hYffFb&client_secret=67868687&grant_type=refresh_token&refresh_token=eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiI0N2E4OGY0MS04ZTI5LTRhMTQtOWZlYi0wZjM0OTM2ZDk0M2QiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDEyODQ5OCwiY2xpZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODkyODQ5OH0.lDvGlZvjkgY5pcJEG5Y1d6o7mOiZA-up2MsGm6zVhZdZxiSDt7md7Ih4_Lkko63_-Fz6UXMg7SLt6ypVJqn3u2iqKRy8aiuSxhQCwAuenoqFFdsFEEqlqkEtDZeo6B3_YrrTeCdjyP_cpLf7vr9GKJS3k5snYGhL8sZrEQMxJaQsyz6F_IPrxajmMiLt4nJUJJgRTjF-krt8p-BBLGxOYCBXe8UPrpsmLnxlEPiwJcFYREimEMSkeD2uDShWXe-ociLWFtoXmYx50TDk_fx2hKRaOVHtnaQJdsgtnQrlc0UkFAOzp9fU45O2Vei7x8SPNA47NdoR1XmPK2ZnXm_TIA

Sample Token-Refresh Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiI0Y2E5NGUyNy04NzkzLTRmOGQtYjY4YS01OWM0MjMwODlhZDAiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDE5NjM0MiwiY2xpZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODk5NjM0Mn0.cmYor7iW6lxRCiM3kWPKauMsiKNGwRrrRFKowcTdkRQewqbQ0Mn9As1RhZwDKL4duxCzAzLw4e8aV8PUyd2-_eCUsqbPMWLWjGo75eU8GI9rrvSGTxEP-fr6jPAr-jBJekQTzMLgkKVtSGaJgtz08dHqrJnrejR8rZs4h1GpPMk6i99cOVMHjuTV7ZzognvkLKj_OR01H4XK5M8TWH5uoAXWrII3K-JJV1YkzjpVkpS0tVXTIXJI-pk_eNeBaJ7Q6in9X3xQKXnIqA8I8zxZt3LNnxR-aui2yufzP5BDh2kfwU0B1Uq8fEuqNmbj4HN1NrmnTHkRJTZ4ooYoqAQtnQ",
  "token_type": "bearer",
  "refresh_token": "eyJraWQiOiI4MGI2ZDJjM2NkZGRkMmY2NmY3MmRjYjIyMmZiNGM1MCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiI4N2IxNDg2MC03YzI0LTQ0NmQtOWJlYS05Mzk2ZDI3MmNmOWQiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwiZGVsZXRlIl0sImlhdCI6MTQ3MTU3MDE5NjMyMywiY2xpZW50X2lkIjoiOGw1N0lZZmZGYiIsIm1lcmNoYW50X2lkIjoiMzI1MzY4IiwiZXhwaXJlc19pbiI6MTQ3MTU5ODk5NjMyM30.Fn8ZlXgvGBr-uvDi6e7-72g8tP-u42T5FNW5NW4YQ7GkrMqUEthexGc9NOcf6uWYfSD4EiSbDVO8EIojZzIUgyXmG3tYDgSejFcDSPcMrF11m9WkOcapbIFTnFk2OyPVi48BVZ6vNb7j2184pJ3KHKoq9E7qlaKrEbvBn2HRVdtvb1yj1Xv1tH38I6Qong8xMAEMCcIfzTinEOFIbENYzgxBsSNVrS15CYtDRFEDPGmAVPzd4I7HN_ed-pzOET3YbUBBQUbrAuZSrSrBcgfBCtT9C5szd7tYXmi-1AMVdFybnVXArAXsDX0nZzm-PuCi_DGKMJET0sY2QNyesyKv8w",
  "expires_in": 28798,
  "scope": "read write delete",
  "refresh_token_expires_in": 28799,
  "client_status": "active"
}

Error Responses

HTTP Status Code	Error	Error Description	Notes
`400`	`invalid_request`	The request is missing a required parameter.	Remove `device_id`.
`400`	`invalid_client`	Invalid client .	Returned if the client ID does not exist in our database.
`400`	`expired_client`	Client status is expired.	Client status is set to expired in the database.
`400`	`invalid_grant`	Unauthorized grant type.	Returned if the client requests a grant type that is not supported by this client.
`400`	`invalid_grant`	Login failure.	Either the username or merchant is not valid, the account is disabled or locked, or the password is invalid or has expired.
`500`	`server_error`	Unable 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

<?xml version="1.0" encoding="utf-16"?>
<updateMerchantDetailsRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="AnetApi/xml/v1/schema/AnetApiSchema.xsd">
  <merchantAuthentication>
	<accessToken>eyJraWQiOiIyNmRjYjVkZTdlMmYwYTI0ODg0MjU1YjIwZWJjMGY0MSIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiI2MzdkNmE1MC1jZGU5LTRiMGUtOWU4Yy1iNWEwMzRkZjk4NzciLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIl0sImlhdCI6MTQ5Njk0NzgyMDgyOSwiYXNzb2NpYXRlZF9pZCI6IjQ4NTA1NSIsImNsaWVudF9pZCI6IkNWWkNKMzhGOGgiLCJtZXJjaGFudF9pZCI6IjU2ODc0MCIsImFkZGl0aW9uYWxJbmZvIjoie1wiYXBpTG9naW5JZFwiOlwibWJsZF9hcGlfJDcyeDN6RDUgICBcIixcInJvdXRpbmdJZFwiOlwiJCRtYmxkX2FwaV8kNzJ4M3pENSQkXCJ9IiwiZXhwaXJlc19pbiI6MTQ5Njk0ODcyMDgyOSwiZ3JhbnRfdHlwZSI6ImF1dGhvcml6YXRpb25fY29kZSJ9.cgmhYKOXzIvpcIHGRhWOaibXPc5YGTHM9IItUswPc07N0Bjj0WpI8T42IzEj18nv675hgsxiUPTmnyE2vUYl0L4aubkCLsoK6HEgGNZEP3Uh8nTEukkh2DMZaOLwcnZvTV7LtVIBAsQ6jiEwhNosg6X3R_CXgKHcDtYGA1NpI8-Nu_KFwwhpmc9MVHT-RIIWwWldQwL2zV5aewMwNcnq9xUCdzCQhAgo_Gn_-OveEEeEEA7N8N6jg5ttUwtD7gRgvbo4JQTJ7eL_WWNAYGRpawlGfqY-9tPLmx3zXkyUICE3CLsqWxR3po0RPtxQLIXYrlVPDoHvzj339zI_ihFsVQ</accessToken>
  </merchantAuthentication>
  <isTestMode>false</isTestMode>
</updateMerchantDetailsRequest >

Authenticating API Requests With OAuth 2.0

Overview

Endpoint URLs

Registering Your Application

Redirecting the Merchant

Sample URL for Obtaining an Authorization Code

Error Responses

Retrieving the Access Token

Sample Token Request

Token Request Parameters

Sample Token Response

Error Responses

Submitting API Requests

Error Responses

Refreshing the Access Token

Sample Token-Refresh Request

Sample Token-Refresh Response

Error Responses

Revoking Permissions

Boarding Integration

Landing Page Flow

MINT Login Page Flow

Setting the Merchant Account to Live Mode

Example isTestMode Request

Example `isTestMode` Request