Automated Recurring Billing (ARB) Guide ARB

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 30

Download
Open PDF In Browser	View PDF

Merchant Web Services API
Automated Recurring Billing™ (ARB)
XML Guide

Authorize.Net Developer Support
http://developer.authorize.net

Authorize.Net LLC 042007 Ver.1.0

Authorize.Net LLC (“Authorize.Net”) has made efforts to ensure the accuracy and completeness of
the information in this document. However, Authorize.Net disclaims all representations, warranties
and conditions, whether express or implied, arising by statute, operation of law, usage of trade,
course of dealing or otherwise, with respect to the information contained herein. Authorize.Net
assumes no liability to any party for any loss or damage, whether direct, indirect, incidental,
consequential, special or exemplary, with respect to (a) the information; and/or (b) the evaluation,
application or use of any product or service described herein.
Authorize.Net disclaims any and all representation that its products or services do not infringe upon
any existing or future intellectual property rights. Authorize.Net owns and retains all right, title and
interest in and to the Authorize.Net intellectual property, including without limitation, its patents,
marks, copyrights and technology associated with the Authorize.Net services. No title or ownership
of any of the foregoing is granted or otherwise transferred hereunder. Authorize.Net reserves the
right to make changes to any information herein without further notice.

Authorize.Net Trademarks
Authorize.Net®
Authorize.Net Your Gateway to IP Transactions™
Authorize.Net Verified Merchant Seal™
Authorize.Net Where the World Transacts®
Automated Recurring Billing™
eCheck.Net®
Fraud Detection Suite™
FraudScreen.Net®

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Table of Contents
Revision History ............................................................................... 3
Section 1 .......................................................................................... 4
Developer Introduction .................................................................... 4
Minimum Requirements ..................................................................................................5
Developer Support ..........................................................................................................5

Section 2 .......................................................................................... 6
Executing an API Call ...................................................................... 6
ARB API URLs ................................................................................................................6
ARB Subscription Functions ............................................................................................7
Authentication ............................................................................................................................ 7
Input Elements for ARBCreateSubscriptionRequest ............................................................. 8
Input Elements for ARBUpdateSubscriptionRequest .......................................................... 14
Input Elements for ARBGetSubscriptionStatusRequest ..................................................... 16
Input Elements for ARBCancelSubscriptionRequest .......................................................... 17

Section 3 ........................................................................................ 18
XML Responses.............................................................................. 18
Responses for Successful Requests .............................................................................18
Output Elements for ARBCreateSubscriptionResponse ..................................................... 18
Transaction Response for Individual Payments in a Subscription .................................... 20
Output Elements for ARBUpdateSubscriptionResponse and
ARBCancelSubscriptionResponse ........................................................................................ 22
Output Elements for ARBGetSubscriptionStatusResponse ............................................... 22

Response Codes ...........................................................................................................24
Response Codes ...................................................................................................................... 25
Duplicate Subscription Verification ....................................................................................... 27
General Errors for Individual Payments in a Subscription ................................................. 28

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Revision History
PUBLISH DATE

UPDATES

January 2007

Initial release of the Automated Recurring Billing (ARB) API

August 3, 2007

Updated description for response code E00012

September 24, 2007

No end date/Silent Post URL updates

May 2008

Removal of SecureSource requirements and various updates
Clarification of subscription start date validation
Add ERR00045
Clarify CardCode element usage

October 2009

Correct hyperlinks

February 2010

Clarifications suggested by Customer Support

June 2010

Correct misspelling on page 5

August 2010

Added ARBGetSubscriptionStatusRequest and
ARBGetSubscriptionStatusResponse

February 2011

Clarify monthly interval for end of month
Update list of error codes

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 1
Developer Introduction
This guide describes the Web development required to submit Automated Recurring Billing™
(ARB), or subscription-based, payments to the Authorize.Net Payment Gateway directly from a
Web site or other application using extensible markup language (XML).
Specifically, the Authorize.Net ARB Application Programming Interface (API) provides a
mechanism for developers and value added resellers (VARs) to create, update and cancel ARB
subscriptions by means of direct integration between client software or applications and the
Authorize.Net Payment Gateway.
A subscription is a set of multiple transactions, or payments, created for the purchase of a
subscription-based product or service or for an installment-based payment plan. Payments for the
subscription are then generated by the payment gateway at later dates based on a specified payment
schedule and subscription duration.
ARB subscriptions do not process transactions in real-time. A successful creation of an ARB
subscription transaction is not an indicator that the subscription payments that process through your
account will be successful. ARB subscription transactions process at approximately 2am PST on
their scheduled payment dates. This means that the first scheduled transaction will not be sent to the
customer’s bank for authorization until approximately 2am PST on the start date that you specify
upon creating the subscription in your account. If you create a subscription with a start date that
equals the creation date, the first scheduled payment will not process until after 2am the following
day. If you wish to validate your customer’s payment information before creating their subscription
in your account, please use one of the real-time transaction processing methods, such as the AIM
(Advanced Integration Method).
The behavior of the ARB API is the same as when a merchant creates, updates, and cancels ARB
subscriptions in the Merchant Interface. When a merchant creates a subscription in the Merchant
Interface, they enter all required information (customer payment information, subscription interval
and duration, etc.) into the Create New ARB Subscription form. When the merchant submits the
information, the Subscription Confirmation page returns a message to the merchant regarding
whether or not the subscription was created successfully. The subscription ID assigned for a
successfully created subscription is also displayed.
The ARB API accomplishes these same functions through an XML call and subsequent XML
response. Whether a subscription is created in the Merchant Interface or through the ARB API, the
results are the same.
Note:

You may want to log on to the Merchant Interface to step through the manual ARB process.
If you do not have a live production account to use for this purpose, you can request a
developer test account from our Developer Center at
http://developer.authorize.net/testaccount. Be sure to include in the comments section that
you need the ARB feature enabled for your test account. Please note that ARB subscription
transactions never process through our test environment, so if you use a test environment
account, you will never see an ARB subscription transaction process. If you wish to see an
ARB subscription transaction process, you MUST use your live production account.

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 1: Developer Introduction

Minimum Requirements
Before you begin ARB integration for an Authorize.Net Payment Gateway account, please check
with the merchant to make sure that the following minimum requirements have already been met.
•

The merchant must have a merchant bank account that allows Internet transactions.

•

The merchant must have an active Authorize.Net Card Not Present Payment Gateway
account.

•

The merchant must be signed up for the Authorize.Net ARB service.

•

Test Mode must be disabled.

•

The merchant must store account authentication data securely (for example, API login ID,
transaction key).

Note:

Merchants should avoid storing any type of sensitive cardholder information. However, in
the event that a merchant or third party must store sensitive customer business or payment
information, compliance with industry standard storage requirements is required. Please
see the Developer Security Best Practices White Paper for guidelines.

Developer Support
There are several resources available to help you successfully integrate a merchant Web site or
other application to the Authorize.Net Payment Gateway.
•

The Developer Center at http://developer.authorize.net provides test accounts, sample code,
FAQs, and troubleshooting tools.

•

Be sure to read our Developer Security Best Practices White Paper at
http://www.authorize.net/files/developerbestpractices.pdf for information on how to
maximize the security and reliability of your merchant integration solutions.

•

If you have questions about the information you find in the Developer Center, you can
contact Integration Services by email at integration@authorize.net.

If you have any suggestions about how we can improve or correct this guide, please email
documentation@authorize.net.

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 2
Executing an API Call
The following sections describe the minimum requirements for executing an API call for an ARB
subscription request using XML.
There are two options for developing the subscription request script:
•

You can develop a custom script yourself using the API fields information in this section,
OR

•

You can use Authorize.Net sample code in C#, Java, PHP, Ruby, and VBNet available for
free from our Developer Center at http://developer.authorize.net/samplecode. We try to
offer the most requested programming languages for sample code, but unfortunately we
cannot offer all programming languages requested. If you do not wish to use the ARB
sample code that we offer, please use your knowledge of your chosen language, along with
this guide, to create your own.

Note:

If you choose to use Authorize.Net sample code, please be aware that in order to achieve a
successful implementation it must be modified with the merchant’s specific payment
gateway account information.

Note for .NET programmers: When a parameter is optional, and if you use serialization, then the
.NET language you are using automatically creates Boolean properties that indicate whether or not
non-nullable parameters are specified. For example, if there is a parameter named validationMode
that is an Enumeration type, a parameter called validationModeSpecified will automatically be
created. By default, these properties are set to “false.”If a request passes a value for an optional
parameter, be sure to set these properties to “true” so that the value is not ignored.

ARB API URLs
ITEM

LOCATION

Production

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

Developer Test

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

XML Schema

https://api.authorize.net/xml/v1/schema/AnetApiSchema.xsd

In order to be processed successfully, API requests and responses must conform to the ARB API
XML schema.
Note: The Developer Test URL requires the use of a developer test payment gateway account.
Production accounts cannot be used to test against the developer test URL, and vice
versa.
Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 2: Executing an API Call

ARB Subscription Functions
The ARB API includes the following functions:
•

ARBCreateSubscriptionRequest

•

ARBUpdateSubscriptionRequest

•

ARBGetSubscriptionStatusRequest

•

ARBCancelSusbscriptionRequest

Each API submission may contain only one ARB request. Including more than one request per
submission will result in an error.

Authentication
ALL calls to the ARB API require merchant authentication. The following table represents the
required XML elements. All XML elements are case sensitive and must be submitted in the
order listed here. Optional elements should not be submitted unless they contain valid values.

ELEMENT

VALUE

merchantAuthentication

Contains the
merchant’s payment
gateway account
authentication
information

FORMAT

NOTES

Submit the API login ID used to
submit transactions.

name

The merchant’s valid
API login ID

Up to 25
characters

transactionKey

The merchant’s valid
transaction key

16 characters Submit the transaction key
obtained by the merchant from
the Merchant Interface.

Example of Authentication with the API Login ID and Transaction Key

mytestacct
112223344

Note:

The sample code included in this document uses dummy field values. When using or
testing sample code, be sure to enter valid field values. Additional sample code is available
for download from the Authorize.Net Developer Center at
http://developer.authorize.net/samplecode.

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

Input Elements for ARBCreateSubscriptionRequest
The following table represents the input elements for executing an API call to the
ARBCreateSubscriptionRequest function, in addition to the authentication elements. Indentations in
the Element column indicate grouping hierarchy. Elements are required unless otherwise
indicated. All XML elements are case sensitive and must be submitted in the order listed
here. Optional elements should not be submitted unless they contain valid values.
ELEMENT

VALUE

FORMAT

NOTES

refId

Merchant-assigned
reference ID for the
request

Up to 20
characters

If included in the request, this
value will be included in the
response. This feature might be
especially useful for multithreaded applications.

Optional
subscription

name

Contains information
about the subscription
Merchant-assigned
name for the
subscription

Up to 50
characters

Optional
paymentSchedule

interval

length

Contains information
about the payment
schedule
Contains information
about the interval of
time between
payments
The measurement of
time, in association
with the Interval Unit,
that is used to define
the frequency of the
billing occurrences

Up to 3 digits
If the Interval
Unit is
"months," can
be any
number
between one
(1) and 12.
If the Interval
Unit is "days,"
can be any
number
between
seven (7) and
365.

unit

The unit of time, in
association with the
Interval Length,
between each billing

days, months

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 2: Executing an API Call

ELEMENT

VALUE

FORMAT

NOTES

YYYY-MMDD

The date entered must be greater
than or equal to the date the
subscription was created.

occurrence
startDate

The date the
subscription begins
(also the date the
initial billing occurs)

The validation checks against
local server date, which is
Mountain Time. An error might
possibly occur if you try to submit
a subscription from a time zone
where the resulting date is
different; for example, if you are
in the Pacific time zone and try to
submit a subscription between
11:00 PM and midnight, with a
start date set for today.
st

Note: If the start date is the 31 ,
and the interval is monthly, the
billing date is the last day of each
month (even when the month
does not have 31 days).
totalOccurrences

Number of billing
occurrences or
payments for the
subscription

Up to 4 digits

To submit a subscription with no
end date (an ongoing
subscription), this field must be
submitted with a value of “9999.”
If a trial period is specified, this
number should include the Trial
Occurrences.

trialOccurrences

Number of billing
occurrences or
payments in the trial
period

Up to 2 digits

If a trial period is specified, this
number must be included in the
Total Occurrences.

Optional
amount

The amount to be
billed to the customer
for each payment in
the subscription

Up to 15
digits

If a trial period is specified, this is
the amount that will be charged
after the trial payments are
completed.

trialAmount

The amount to be
charged for each
payment during a trial
period

Up to 15
digits

Required when trial occurrences
is specified.

Conditional

payment

Once the number of trial
occurrences for the subscription
is complete, the regular amount
will be charged for each
remaining payment.

Contains either the
customer’s credit card
or bank account

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

ELEMENT

VALUE

FORMAT

NOTES

payment information
creditCard

Contains the
customer’s credit card
information

This element should only be
included when the payment
method is credit card.

cardNumber

The credit card
number used for
payment of the
subscription

13 to 16
digits

expirationDate

The expiration date of
the credit card used
for the subscription

YYYY-MM

cardCode

The three- or four-digit
card code on the back
of most credit cards,
on the front for
American Express

3 or 4 digits

Optional

bankAccount

Contains the
customer’s bank
account information

This element should only be
included when the merchant has
set the card code value field to
required in the account settings.
The value itself is never
validated.

This element should only be
included when the payment
method is bank account.

accountType

The type of bank
account used for
payment of the
subscription

checking,
businessChe
cking,
savings

routingNumber

The routing number of
the customer’s bank

9 digits

accountNumber

The bank account
number used for
payment of the
subscription

5 to 17 digits

nameOnAccount

The full name of the
individual associated
with the bank account
number

Up to 22
characters

echeckType

The type of electronic
check transaction
used for the
subscription

For checking
or savings
accounts,
PPD or WEB
For business
checking

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 2: Executing an API Call

ELEMENT

VALUE

FORMAT

NOTES

accounts,
CCD
bankName

The name of the bank
associated with the
bank account number

Up to 50
characters

Optional
order

Contains optional
order information
Optional

invoiceNumber

Merchant-assigned
invoice number for the
subscription

Up to 20
characters

The invoice number will be
associated with each payment in
the subscription.

Up to 255
characters

The description will be
associated with each payment in
the subscription.

Optional
description

Description of the
subscription
Optional

customer

Contains information
about the customer
Merchant-assigned
identifier for the
customer

Up to 20
characters

Optional
email

The customer’s email
address

Up to 255
characters

Optional
phoneNumber

The customer’s phone
number

Up to 25
digits

Optional
faxNumber

The customer’s fax
number

Up to 25
digits

Optional
billTo

firstName

Contains the
customer’s billing
address information
The first name
associated with the

Up to 50
characters

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

ELEMENT

VALUE

FORMAT

NOTES

customer’s billing
address
lastName

The last name
associated with the
customer’s billing
address

Up to 50
characters

company

The company
associated with the
customer’s billing
address

Up to 50
characters

Optional
address

The customer’s billing
address

Up to 60
characters

Optional
city

The city of the
customer’s billing
address

Up to 40
characters

Optional
state

zip

The state of the
customer’s billing
address

2 characters

Optional

Must be a
valid state
code

The ZIP code of the
customer’s billing
address

Up to 20
characters

Optional
country

The country of the
customer’s billing
address
Optional

shipTo

Up to 60
characters
Must be a
valid twocharacter
country code
or full country
name
(spelled in
English).

Contains the
customer’s shipping
address information

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 2: Executing an API Call

ELEMENT

VALUE

FORMAT

NOTES

Optional
firstName

The first name
associated with the
customer’s shipping
address

Up to 50
characters

lastName

The last name
associated with the
customer’s shipping
address

Up to 50
characters

company

The company
associated with the
customer’s shipping
address

Up to 50
characters

address

The customer’s
shipping address

Up to 60
characters

city

The city of the
customer’s shipping
address

Up to 40
characters

state

The state of the
customer’s shipping
address

Up to 40
characters

zip

The ZIP code of the
customer’s shipping
address

Up to 20
characters

country

The country of the
customer’s shipping
address

Up to 60
characters
Must be a
valid twocharacter
country code
or full country
name
(spelled in
English).

Example ARBCreateSubscriptionRequest

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

mytestacct
112223344

Sample

Sample subscription

1
months

2007-03-15
12
1

10.29
0.00

4111111111111111
2008-08

John
Smith

Note:

Input Elements for ARBUpdateSubscriptionRequest
The input elements for a request to update an ARB subscription are the same as the create an ARB
subscription function with the following addition and exceptions. All XML elements are case
Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 2: Executing an API Call

sensitive and must be submitted in the order listed here. Optional elements should not be
submitted unless they contain valid values.
•

You must submit the subscriptionID of the subscription to be updated.

ELEMENT

VALUE

FORMAT

subscriptionId

The payment gateway
assigned identification
number for the
subscription

Up to 13
digits

NOTES

•

The subscription start date (subscription.paymentSchedule.startDate) may only be updated
in the event that no successful payments have been completed.

•

The subscription interval information (subscription.paymentSchedule.interval.length and
subscription.paymentSchedule.interval.unit) may not be updated.

•

The number of trial occurrences (subscription.paymentSchedule.trialOccurrences) may
only be updated if the subscription has not yet begun or is still in the trial period.

•

All other fields are optional.

Example ARBUpdateSubscriptionRequest

mytestacct
112223344

Sample
100748

4111111111111111
2010-08

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

Note:

Input Elements for ARBGetSubscriptionStatusRequest
The following table represents the input elements for executing an API call to the
ARBGetSubscriptionStatusRequest function, in addition to the authentication elements.
Indentations in the Element column indicate grouping hierarchy. Elements are required unless
otherwise indicated. All XML elements are case sensitive and must be submitted in the order
listed here. Optional elements should not be submitted unless they contain valid values.

ELEMENT

VALUE

refID

Merchant-assigned
reference ID for the
request

FORMAT

If included in the request, this
value will be included in the
response. This feature might be
especially useful for multithreaded applications.

Optional

subscriptionId

The payment gateway
assigned identification
number for the
subscription

NOTES

Up to 13
digits

Example ARBGetSubscriptionStatusRequest

mytestacct
112223344

Sample
100748

Note:

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 2: Executing an API Call

Input Elements for ARBCancelSubscriptionRequest
The following table represents the input elements for executing an API call to the
ARBCancelSubscriptionRequest function, in addition to the authentication elements. Indentations
in the Element column indicate grouping hierarchy. Elements are required unless otherwise
indicated. All XML elements are case sensitive and must be submitted in the order listed
here. Optional elements should not be submitted unless they contain valid values.

ELEMENT

VALUE

refID

Merchant-assigned
reference ID for the
request

FORMAT

If included in the request, this
value will be included in the
response. This feature might be
especially useful for multithreaded applications.

Optional

subscriptionId

The payment gateway
assigned identification
number for the
subscription

NOTES

Up to 13
digits

Example ARBCancelSubscriptionRequest

mytestacct
112223344

Sample
100748

Note:

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 3
XML Responses
The transaction response from the payment gateway is a set of fields that provides information
about the status of a request.

Responses for Successful Requests
The following sections describe the output elements that are returned for successful API calls.

Output Elements for ARBCreateSubscriptionResponse
The following table represents the output elements for a successful API call to the
ARBCreateSubscriptionRequest function. Indentations in the Element column indicate grouping
hierarchy.
ELEMENT

VALUE

FORMAT

NOTES

refID

Merchant-assigned
reference ID for the
request

Up to 20
characters

This element is included in the
response only if it was included in
the request.

messages

Contains information
about the results of the
request
Ok

An “Ok” result code indicates that
the request was processed and
accepted without error.

resultCode

Contains additional
information about the
results of the request

message

Contains the result
code and text

code

I00001

text

Successful

subscriptionId

The payment gateway
assigned identification
number for the
subscription

Any messages present are
informational only.

Up to 13
digits

Example ARBCreateSubscriptionResponse

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 3: XML Responses

Sample

I00001
Successful.

100748

Once you receive a response from the payment gateway with an “Ok” result code, your subscription
has been successfully created. The response will include the subscription ID assigned to that
particular subscription. Individual transactions, or payments, for a subscription are generated
automatically after 2 a.m. PST by the payment gateway according to the designated payment
schedule and subscription duration. Each payment will only be viewable in the merchant’s payment
gateway account when it is actually generated.
For example, if a new subscription is created with a start date of June 6, with a monthly payment
interval, the first payment for the subscription will not be viewable in the merchant’s payment
gateway account until June 6. All subsequent payments will be visible on their scheduled date (July
6 payment will be visible on July 6, August 6 on August 6, etc.).
Note: If you create a new subscription with the first payment scheduled for that same day, the
initial payment for the subscription will actually be submitted the next business day.

Once each scheduled transaction in a subscription has been submitted, which is usually at 2 AM
PST for ARB transactions, the merchant will receive an email from the payment gateway indicating
the transaction status.
The merchant can also configure their account in the Merchant Interface to receive the following
ARB emails:
•

Daily Transaction Summary.

•

Failed Transaction Notice – sent when a payment in a subscription declines or receives an
error response from the processor.

•

Subscription Due for Expiration – sent after the second to last payment in a subscription is
submitted, to notify the merchant that the next payment is the final one in the subscription.

•

Credit Card Expiration – sent immediately after the last possible successful payment in a
subscription, to notify the merchant that the credit card expiration date will expire before
the next scheduled payment in the subscription.

•

Subscription Suspension – sent to notify the merchant that a subscription has been
suspended. A subscription will be suspended if the first payment in the subscription is
declined, rejected or receives an error response. Additionally, if a subscription is edited, for
example payment or shipping information is changed, the subscription will be suspended if
the first payment after the edits is declined, rejected or receives an error response.

•

Subscription Termination – sent when a subscription is terminated. If a suspended
subscription is not edited to fix the problem that caused the suspension, it will terminate on
the next scheduled payment.

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

•

Subscription Expiration – sent after a subscription has expired. Once expired, a
subscription cannot be reactivated. Instead, a new subscription would have to be created.

Note: The Daily Transaction Summary email returns an Excel file in comma separated value
(.csv) format. The merchant will receive Successful.csv, Failed.csv or both files.

To select which ARB emails to receive:
Log on to the Merchant Interface at https://secure.authorize.net
Click User Administration under Account in the main menu on the left
Select the user you would like to edit and click Edit User
Click Edit Profile Information under Profile and Security Settings
Under the Automated Recurring Billing (ARB) Emails section, click to select or deselect which
emails the user should receive
Click Submit to save the changes
Note:

Test environment accounts do not process ARB subscription transactions. If you are using
a test environment account, you will not receive these email notifications in any form. You
will also not be able to receive an ARB subscription transaction Silent Post while using a
test environment account.

For more information on viewing subscriptions in the Merchant Interface or on the types of ARB
emails the merchant can opt to receive, please see the Merchant Interface Online Help Files.

Transaction Response for Individual Payments in a Subscription
The payment gateway sends an email to the merchant for each transaction submitted in a
subscription indicating the transaction’s status. If you would like to receive a transaction response
for each payment in a subscription, you must enable the Silent Post feature in the Merchant
Interface. When this feature is enabled, the payment gateway will post a transaction response in
name/value pair format to the URL specified in the Silent Post field of the Merchant Interface. The
name/value pair response uses the syntax of x_name_of_field=value of field&. You can find a list
of these fields in the SIM Implementation Guide in the section entitled “Fields in the Payment
Gateway Response.”
IMPORTANT: When the Silent Post URL feature is enabled, name/value pair responses for both
ARB transactions and all other non-ARB transactions will post to the specified URL. To determine
which transaction responses are for ARB payments, you can parse the response for the
x_subscription_id (Subscription ID) and the x_subscription_paynum (Subscription Payment
Number) fields. These fields are only returned in ARB subscription transaction responses.
Note:

The Silent Post feature only returns responses for scheduled ARB transactions that are
approved or declined. The payment gateway will not return a response to the specified
Silent Post URL if the scheduled transaction results in a general error due to expired or
invalid payment information. For more information see the “General Errors for Individual
Payments in a Subscription” section of this guide.

Configuring a Silent Post URL In Your Live Production Account.

A Silent Post request must be accepted within 2 seconds, otherwise it will be aborted. If you decide
to use Silent Post, it is important that your Silent Post URL is simply used as a method of collecting
and dumping response data into a database or file for your use separately at a later time. Otherwise,
Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 3: XML Responses

the likelihood of your Silent Post URL failing to accept the responses we send will be much higher.
A Silent Post is sent only once and it is not possible to have them re-sent to you at any time.
ARB subscriptions only generate Silent Post responses if and when a transaction processes. If a
transaction does not process, for example, if the credit card has expired, a Silent Post does not occur
(see General Errors for Individual Payments in a Subscription on page 27 for more information). It
is recommended that you configure the ARB specific email notifications within your account as
well as using Silent Post for the purposes of identifying ARB subscription activity.
Silent Post responses are returned in real-time, meaning as soon as the transaction processes we
send out the Silent Post to your specified URL. We do not necessarily update the subscription in
real-time, however. This means that you should not use the Silent Post response to immediately
update or cancel an ARB subscription. If you update or cancel a subscription before we have
updated the subscription in our system, our update will overwrite any changes you may have made.
You should instead simply collect the response data and submit any changes necessary in your
subscription(s) later that day.
For information on how to configure the Silent Post URL in the Merchant Interface, see the
Merchant Integration Guide at http://www.authorize.net/support/merchant/.
An ARB subscription transaction Silent Post will occur when ARB transactions are processed in
your live production account. ARB subscriptions begin processing at approximately 2am PST.
Because the POST does not occur while an SSL connection is established, ARB transactions use an
MD5 Hash calculation to validate each transaction response. If you do not have the Silent Post
feature enabled, the MD5 Hash information below is not applicable.
Using the MD5 Hash Feature for ARB Transactions

The MD5 Hash feature enables you to authenticate that a transaction response is securely received
from Authorize.Net. The payment gateway creates the MD5 Hash using the following pieces of
account and transaction information as input:
•

MD5 Hash value—this is the value set by the merchant in the Merchant Interface

•

API Login ID (x_login)

•

Transaction ID (x_trans_id)

•

Amount (x_amount)

Formatted: Font: Italic

The MD5 Hash value is a random value configured by the merchant in the Merchant Interface. It
should be stored securely separately from the merchant’s Web server. For more information on how
to configure this value, see the Merchant Integration Guide
athttp://www.authorize.net/support/merchant/.
For example, if the MD5 Hash value configured by the merchant in the Merchant Interface is
“wilson,” and the transaction ID is “9876543210” with an amount of $1.00, then the field order
used by the payment gateway to generate the MD5 Hash would be as follows:
wilson98765432101.00
Note:

The value passed back for x_amount is formatted with the correct number of decimal
places used in the transaction. For transaction types that do not include a transaction
amount, mainly Voids, the amount used by the payment gateway to calculate the MD5
Hash is “0.00.”

To authenticate the MD5 Hash returned by the payment gateway in the transaction response, you
will need to create a script that can receive and parse the transaction response, call the merchant’s
Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

MD5 Hash value, and run the MD5 algorithm on the same fields listed above. If the result matches
the MD5 Hash returned by the payment gateway, the transaction response is successfully
authenticated.
The fields listed above are only applicable when using the MD5 Hash for ARB transactions. If you
are using the MD5 Hash to authenticate non-ARB transactions, the fields used are different. For
information on using the MD5Hash for non-ARB transactions, see the Merchant Integration Guide
at http://www.authorize.net/support/merchant/.
Example Silent Post Response
x_response_code=1&x_response_subcode=1&x_response_reason_code=1
&
x_response_reason_text=This+transaction+has+been+approved%2E&
x_auth_code=QbJHm4&x_avs_code=Y&x_trans_id=2147490176&
x_invoice_num=INV12345&x_description=My+test+description&
x_amount=0%2E44&x_method=CC&x_type=auth%5Fcapture&
x_cust_id=CustId&x_first_name=Firstname&
x_last_name=LastNamenardkkwhczdp&x_company=&x_address=&x_city=&
x_state=&x_zip=&x_country=&x_phone=&x_fax=&x_email=&
x_ship_to_first_name=&x_ship_to_last_name=&x_ship_to_company=&
x_ship_to_address=&x_ship_to_city=&x_ship_to_state=&x_ship_to_z
ip=&
x_ship_to_country=&x_tax=0%2E0000&
x_duty=0%2E0000&x_freight=0%2E0000&x_tax_exempt=FALSE&x_po_num=
&
x_MD5_Hash=B9B3D19AEFD7BECC86C5FB3DB717D565&
x_cavv_response=2&x_test_request=false&x_subscription_id=101635
&
x_subscription_paynum=1

Output Elements for ARBUpdateSubscriptionResponse and
ARBCancelSubscriptionResponse
The output elements for ARBUpdateSubscriptionResponse and ARBCancelSubscriptionResponse
are the same as ARBCreateSubscriptionResponse with the following exception:
•

The subscriptionID of the updated subscription is not included in the response.

Output Elements for ARBGetSubscriptionStatusResponse
The following table describes output elements for ARBGetSubscriptionStatusResponse.
ELEMENT

VALUE

FORMAT

NOTES

refID

Merchant-assigned
reference ID for the
request

Up to 20
characters

This element is included in the
response only if it was included in
the request.

messages

Contains information
about the results of the
request
Ok

An “Ok” result code indicates that
the request was processed and
accepted without error.

resultCode

Contains additional
information about the
results of the request

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

Section 3: XML Responses

ELEMENT

VALUE

message

Contains the result
code and text

code

The response code
that represents the
status

text

A text description of
the status

Status

Contains information
about the subscription
status

FORMAT

NOTES
Any messages present are
informational only.

Possible
values:
active,
expired,
suspended,
canceled,
terminated

Example ARBGetSubscriptionStatusResponse

Sample

I00001
Successful

active

Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

Response Codes
The following table describes the output elements for a status response to any of the requested API
methods.

ELEMENT

VALUE

FORMAT

NOTES

refID

Merchant-assigned
reference ID for the
request

Up to 20
characters

This element is included in the
response only if it was included in
the request.

Messages

Contains information
about the results of the
request

resultCode

Contains additional
information about the
status of the request

Message

Contains the result
code and text

Code

The response code that
represents the status

Text

A text description of the
status

Messages provide more details
about the status.

Example Error Response

Error

E00003
An error occurred while parsing the XML
request.

Section 3: XML Responses

Response Codes
The following table lists the common response codes and texts.
CODE

TEXT

DESCRIPTION

I00001

Successful

The record was processed successfully.

I00003

The record has already been deleted.

E00001

An error occurred during processing. Please try An unexpected system error occurred while
again.
processing this request.

E00002

The content-type specified is not supported.

The only supported content-types are text/xml
and application/xml.

E00003

An error occurred while parsing the XML
request.

This is the result of an XML parser error.

E00004

The name of the requested API method is
invalid.

The name of the root node of the XML request
is the API method being called. It is not valid.

E00005

The merchantAuthentication.transactionKey is
invalid or not present.

Merchant authentication requires a valid value
for transaction key.

E00006

The merchantAuthentication.name is invalid or
not present.

Merchant authentication requires a valid value
for name.

E00007

User authentication failed due to invalid
authentication values.

The name/and or transaction key is invalid.

E00008

User authentication failed. The payment
gateway account or user is inactive.

The payment gateway or user account is not
currently active.

E00009

The payment gateway account is in Test Mode. The requested API method cannot be executed
The request cannot be processed.
while the payment gateway account is in Test
Mode.

E00010

User authentication failed. You do not have the
appropriate permissions.

The user does not have permission to call the
API.

E00011

Access denied. You do not have the
appropriate permissions.

The user does not have permission to call the
API method.

E00012

A duplicate subscription already exists.

A duplicate of the subscription was already
submitted. The duplicate check looks at several
fields including payment information, billing
information and, specifically
for subscriptions, Start Date, Interval and Unit.

E00013

The field is invalid.

One of the field values is not valid.

ARB Developer Guide

CODE

TEXT

DESCRIPTION

E00014

A required field is not present.

One of the required fields was not present.

E00015

The field length is invalid.

One of the fields has an invalid length.

E00016

The field type is invalid.

The field type is not valid.

E00017

The start date cannot occur in the past.

The subscription start date cannot occur before
the subscription submission date.
Validation is performed against local server
time, which is Mountain Time.

E00018

The credit card expires before the subscription
start date.

The credit card is not valid as of the start date
of the subscription.

E00019

The customer tax ID or drivers license
information is required.

The customer tax ID or driver’s license
information (driver’s license number, driver’s
license state, driver’s license DOB) is required
for the subscription.

E00020

The payment gateway account is not enabled
for eCheck.Net subscriptions.

This payment gateway account is not set up to
process eCheck.Net subscriptions.

E00021

The payment gateway account is not enabled
for credit card subscriptions.

This payment gateway account is not set up to
process credit card subscriptions.

E00022

The interval length cannot exceed 365 days or
12 months.

The interval length must be 7 to 365 days or 1
to 12 months.

E00024

Trial Occurrences is required when Trial
Amount is specified.

The number of trial occurrences cannot be zero
if a valid trial amount is submitted.

E00025

Automated Recurring Billing is not enabled.

The payment gateway account is not enabled
for Automated Recurring Billing.

E00026

Both Trial Amount and Trial Occurrences are
required.

If either a trial amount or number of trial
occurrences is specified then values for both
must be submitted.

E00027

The test transaction was unsuccessful.

An approval was not returned for the test
transaction.

E00028

Trial Occurrences must be less than Total
Occurrences.

The number of trial occurrences specified must
be less than the number of total occurrences
specified.

E00029

Payment information is required.

Payment information is required when creating
a subscription.

Section 3: XML Responses

CODE

TEXT

DESCRIPTION

E00030

The payment schedule is required.

A payment schedule is required when creating
a subscription.

E00031

The amount is required.

The subscription amount is required when
creating a subscription.

E00032

The start date is required.

The subscription start date is required to create
a subscription.

E00033

The subscription start date cannot be changed. Once a subscription is created the Start Date
cannot be changed.

E00034

The interval information cannot be changed.

Once a subscription is created the subscription
interval cannot be changed.

E00035

The subscription cannot be found.

The subscription ID for this request is not valid
for this merchant.

E00036

The payment type cannot be changed.

Changing the subscription payment type
between credit card and eCheck.Net is not
currently supported.

E00037

The subscription cannot be updated.

Subscriptions that are expired, canceled or
terminated cannot be updated.

E00038

The subscription cannot be canceled.

Subscriptions that are expired or terminated
cannot be canceled.

E00040

The customer profile ID, payment profile ID,
shipping address ID, or transaction ID for this
request is not valid for this merchant.

E00042

You cannot add more than 10 payment
profiles.

E00043

You cannot add more than 100 shipping
addresses.

E00045

The root node does not reference a valid XML
namespace.

An error exists in the XML namespace. This
error is similar to E00003.

Duplicate Subscription Verification
A duplicate check occurs against every ARB subscription created in an account in order to prevent
duplicate subscriptions from inadvertently being created. The following is a list of the fields which
are verified. If ALL of the verified fields are the same, an E00012 will occur and the subscription
will not be successfully created in the account. The duplicate check verifies for an indefinite
amount of time.
Last revised: 6/3/2011
Copyright © 1998 - 2008 Authorize.Net, a CyberSource solution

ARB Developer Guide

•

subscription.Article.MerchantID

•

subscription.Article.CustomerInfo.Payment.CreditCard.CardNumber

•

subscription.Article.CustomerInfo.Payment.eCheck.RoutingNumber

•

subscription.Article.CustomerInfo.Payment.eCheck.AccountNumber

•

subscription.Article.CustomerInfo.CustomerID

•

subscription.Article.CustomerInfo.BillingInfo.BillToAddress.FirstName

•

subscription.Article.CustomerInfo.BillingInfo.BillToAddress.LastName

•

subscription.Article.CustomerInfo.BillingInfo.BillToAddress.Company

•

subscription.Article.CustomerInfo.BillingInfo.BillToAddress.StreetAddress

•

subscription.Article.CustomerInfo.BillingInfo.BillToAddress.City

•

subscription.Article.CustomerInfo.BillingInfo.BillToAddress.StateProv

•

subscription.Article.CustomerInfo.BillingInfo.BillToAddress.Zip

•

subscription.OrderInfo.Amount

•

subscription.OrderInfo.Invoice

•

subscription.Recurrence.StartDate

•

subscription.Recurrence.Interval

•

subscription.Recurrence.Unit

General Errors for Individual Payments in a Subscription
Anytime an error occurs that prevents the payment gateway from processing a scheduled payment
in a subscription, the payment will result in a general error. For example, if the credit card
expiration date on file for a subscription is not updated before it expires, the next scheduled
payment will not be processed and the transaction will result in a general error. These subscriptions
will not be suspended or be automatically terminated unless the general error occurs on the first
scheduled payment in the subscription.
Note:

If the Silent Post feature of the Merchant Interface is enabled, transactions that receive a
general error will NOT post a response to the specified Silent Post URL. See the
“Transaction Response for Individual Payments in a Subscription” section of this guide for
more information on using the Silent Post feature.

Some of the most common reasons for a payment to receive a general error are:
•

The credit card number or expiration date on file has expired.

•

The payment gateway account was in test mode at the time of the scheduled payment.

•

eCheck.Net has been disabled for the payment gateway account or the specific eCheck.Net
type has been disabled.

•

A notice of change (NOC) has been received for the eCheck.Net subscription.

Section 3: XML Responses

Payments with general errors can be identified on the completed transactions page of the Merchant
Interface. They will display “N/A” in the Transaction ID field and “General Error” in the
Transaction Status field.
Note:

Transactions that result in general errors can also be found in the Failed.csv Excel file that
comes when you are enabled to receive the Daily Transaction Summary email.

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Author                          : alegsdin
Company                         : Authorize.Net, a Service of Lightbridge
Create Date                     : 2011:06:03 11:56:16-07:00
Modify Date                     : 2011:06:03 11:56:49-07:00
Source Modified                 : D:20110324221149
Tagged PDF                      : Yes
XMP Toolkit                     : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-20:48:00
Metadata Date                   : 2011:06:03 11:56:49-07:00
Creator Tool                    : Acrobat PDFMaker 9.0 for Word
Document ID                     : uuid:e46fd528-15f9-4590-ba55-ca240ea32968
Instance ID                     : uuid:fffb3565-f89f-4645-83a3-c6fc70d9463c
Subject                         : 23
Format                          : application/pdf
Title                           : Automated Recurring Billing (ARB) guide
Creator                         : alegsdin
Producer                        : Adobe PDF Library 9.0
Page Layout                     : OneColumn
Page Mode                       : UseOutlines
Page Count                      : 30

EXIF Metadata provided by EXIF.tools

Automated Recurring Billing (ARB) Guide ARB

Navigation menu

Versions of this User Manual:

Views

Navigation