If you are new to the Authorize.net API, we suggest that you begin with this tutorial. Because Authorize.net is a payment gateway, our most commonly used API method is the request to process a payment transaction using a payment card. This method is sometimes called an authorize-and-capture transaction because it requests both authorization and capture of the payment transaction in a single request. We recommend that you begin with this method, even if you do not expect to use it directly in your final product. Many components of this method are used throughout the API and the communication for all methods uses the same process of sending a request and parsing the response.
Instead of showing you every possible way of constructing the transaction request, this guide summarizes the most commonly used components and builds a sample request. To see every data field that is available, or to review the order of these elements, you can use our API Reference Guide.
The minimum data required for transaction requests are authentication, payment information, and payment amount. For best practices, most transactions will also include information such as a billing address, order details, and customer details.
For this example, authentication is performed using an API login ID and transaction key.
The first value to specify for any transaction request is what type of transaction to process. When you use the payment card payment type, you can choose between either authorize-only (authOnlyTransaction) or authorize-and-capture (authCaptureTransaction). The default if no transaction type is specified is an authorize-and-capture transaction type, however, the recommended best practice is to always explicitly identify the transaction type.
The payment amount is the only paramter that is absolutely required other than the payment details. The payment amount should be specified using standard decimal notation. The currency type is not defined in this field.
The payment object includes the required details for the method of payment. This can be payment card details, bank account information, or tokenized payment information from a service such as Apple Pay.
A traditional payment card is, by far, the most commonly used payment type for processing a transaction. Payment cards can be used for any API call that takes the payment type object as an input.
When charging a payment card, you will need at least the card number and expiration date. For improved security, we strongly recommended that you also collect and validate the Card Code. When testing in the sandbox environment, you can use test-card numbers. For more information about testing, see our Testing Guide.
| Field Name | Description | Format | Required |
|---|---|---|---|
| The 13-16-digit payment card number. | 16-digit, Numeric. | Yes |
| The payment card's expiration date (month and year). | MMYY | Yes |
| The 3 or 4 digit card code. | 3-4 digit, numeric | No |
The order information is not required, but is stored along with the transaction at Authorize.net. Including the order information enables you to more easily identify transactions for your account and makes the data available to other applications that integrate with the same Authorize.net account, for example, reporting or analytics applications. In some cases, the invoice number may also be passed to the card-issuing bank during a payment card authorization.
The two basic fields for order information consist of an invoice number and an order description.
For even more precision in your reporting, you can also provide a further breakdown of data into line item details, which include individual item prices, descriptions, and quantities.
The customer details include your own unique identifier for the customer along with the email address to be used for communication such as email receipts.
The billing address is strongly recommended for the purposes of address verification when processing a payment card. The address is not validated for all payment types and not every field is validated even for payment cards, but it is a best practice to capture the full address.
The shipping address does not apply in all scenarios, but is still a common element for most payment transactions. This address is not validated against the payment method, but it can be validated as a real, shippable address by using the Advanced Fraud Detection Suite.
As mentioned at the beginning of this section, this is only one sample request and does not cover every possible field. To review the full API specification, you will want to review the API Reference. That being said, all of the above fields can be grouped into a single transaction request object that can be communicated with the Authorize.net API.
Sample Create Transaction RequestAfter building the XML object for an API request, submit it to the Authorize.net payment gateway as a standard HTTPS POST to an Authorize.net API endpoint. The exact process for doing this will depend upon the development language that you use.
It is necessary to use the API endpoint that matches the environment of the account that you are testing with. If you attempt to use the credentials for a sandbox account on the production endpoint (or vice versa) you will recieve an error indicating that the authentication has failed.
When you have successfully POSTed the transaction to the Authorize.net API, the immediate response will include the result of the API request, as well as the result of the transaction (if it was processed). It is important to understand how to read this response and determine if the payment was approved.
As you can see below, the complete response includes multiple response fields which indicate the status of separate elements of the original API request. For a complete breakdown of each of these elements, you can see the API Reference. This tutorial shows how to parse the most critical elements.
The messages element is included in every Authorize.net API response. The contents of this message indicate whether the API request was understood and successfully parsed by Authorize.net. The resultCode element will be either Ok or Error. The message code and text can be referenced for more specific detail about an error, if one was encountered.
Importantly, this does not identify whether a transaction was approved or declined by the issuing bank. It only indicates that the transaction was processed by Authorize.net
If the API request was successfully processed (resultCode = Ok), there will also be a response code to indicate the result of submitting the transaction request to the banking network. In a standard payment card transaction, there are only four possible response codes.
In order to determine that a payment card was approved by the cardholder's bank, you must receive both a message code of Ok and a response code of 1.
Response reason codes contain more detailed information about the transaction. For information about specific response reason codes, see our Reason Response Code Tool.
When you have successfully processed a payment, you can move on to other functionality, using the Authorize.net API.
Some of the more popular next steps include:
Reducing PCI Scope with Accept.JS and Accept Hosted
Integrating Customer Profiles to streamline customer payments
Managing Subscriptions for automated scheduled payments Monitoring Account Activity with webhooks
Expand Payment Options by adding support for alternative payments