Search Developer Site

Credit Card Payment Tutorial

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

Authentication

For this example, authentication is performed using an API login ID and transaction key.

Sample Authentication Structure

Transaction Type

The first value to specify for any transaction request is what type of transaction to process. When you use the credit 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.

Sample Transaction Type Declaration

Amount

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.

Sample Amount Structure

Payment

The payment object includes the required details for the method of payment. This can be credit card details, bank account information, or tokenized payment information from a service such as Apple Pay.

A traditional credit card is, by far, the most commonly used payment type for processing a transaction. Credit cards can be used for any API call that takes the payment type object as an input.

When charging a credit 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.

Credit Card Form Fields

Field Name Description Format Required
cardNumberThe 13-16-digit credit card number.16-digit, Numeric.Yes
expirationDateThe credit card's expiration date (month and year).MMYYYes
cardCodeThe 3 or 4 digit card code.3-4 digit, numericNo

Credit Card Payment Structure

Order Information

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 credit card authorization.

The two basic fields for order information consist of an invoice number and an order description.

Sample Order Object

Line Item Details

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.

Sample Line Items

Customer Details

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.

Sample Customer

Billing Address

The billing address is strongly recommended for the purposes of address verification when processing a credit card. The address is not validated for all payment types and not every field is validated even for credit cards, but it is a best practice to capture the full address.

Sample Billing Address

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

Sample Shipping Address

Completed Request

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 Request

Connecting to Authorize.Net

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

API Endpoints

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.

Production: https://api.authorize.net/xml/v1/request.api

Sandbox: https://apitest.authorize.net/xml/v1/request.api

Parsing the Response

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.

Complete Response

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.

Sample Transaction Response

API Request Status

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

Response Messages

Response Code

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 credit card transaction, there are only four possible response codes.

1 - Approved

2 - Declined

3 - Error

4 - Held for Review

In order to determine that a credit card was approved by the cardholder's bank, you must receive both a message code of Ok and a response code of 1.

Reasponse Reason Codes

Response reason codes contain more detailed information about the transaction. For information about specific response reason codes, see our Reason Response Code Tool.