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

  • Authenticating API Requests With OAuth 2.0
    • Overview
    • Endpoint URLs
    • Registering Your Application
    • Redirecting the Merchant
    • Retrieving the Access Token
    • Submitting API Requests
    • Refreshing the Access Token
    • Revoking Permissions
    • Boarding Integration

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

  • OAuth Sample Application
  • Sample Application
  • API Reference

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 developer_feedback@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 URLThis 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.
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 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.

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 the 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.

Important: 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 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 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.

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.
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 the username or merchant is not valid, the account is disabled or locked, or the password is invalid or has 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

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