API v1: Billing Info

Billing information is the information passed to the payment gateway to process a transaction. Typically, it is a combination of a billing address and credit card information.

Create and Update an Account's Billing Information

Creating and updating billing information for an account posts to the same URL. If the billing info does not exist, this API call will create it. If the billing info does exist, this will update the account's billing information.

When the billing information is updated, the credit card is validated and the billing information is only saved if the credit card is valid. When testing a credit card, Recurly attempts a $1.00 authorization and voids the transaction immediately.

If the account has an outstanding balance, Recurly attempts to authorize the card by collecting the balance.

Request

Content-Type: application/xml; charset=utf-8
Accept: application/xml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<?xml version="1.0"?>
<billing_info>
  <first_name>Verena</first_name>
  <last_name>Test</last_name>
  <address1>123 Test St</address1>
  <address2></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <ip_address>192.168.1.1</ip_address>
  <credit_card>
    <number>4111-1111-1111-1111</number>
    <verification_value>123</verification_value>
    <year>2010</year>
    <month>11</month>
  </credit_card>
</billing_info>

Code examples

PHP

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$billing_info = new RecurlyBillingInfo($acct->account_code);
$billing_info->first_name = $acct->first_name;
$billing_info->last_name = $acct->last_name;
$billing_info->address1 = '123 Test St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94105';
$billing_info->credit_card->number = '4111-1111-1111-1111';
$billing_info->credit_card->year = intval(date('Y')) + 1;
$billing_info->credit_card->month = date('n');
$billing_info->credit_card->verification_value = '123';

$updated_billing = $billing_info->update();

Ruby

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

billing_info = Recurly::BillingInfo.create(
  :account_code => account.account_code,
  :first_name => account.first_name,
  :last_name => account.last_name,
  :address1 => '123 Test St',
  :city => 'San Francisco',
  :state => 'CA',
  :zip => '94115',
  :credit_card => {
    :number => '4111-1111-1111-1111',
    :year => Time.now.year + 1,
    :month => Time.now.month,
    :verification_value => '123'
  }
)

Python

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

update_data = {
  'first_name': 'Verena',
  'last_name': 'Doe',
  'address1': '123 Test St',
  'city': 'San Francisco',
  'state': 'CA',
  'country': 'US',
  'zip': '94105',
  'credit_card': {
    'number': '4111-1111-1111-1111',
    'year': '2018',
    'month': '12',
    'verification_value': '123',
  }
}
update_result = recurly.accounts.billing_info.update(account_code=user_id, data=update_data)

C#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

RecurlyBillingInfo billingInfo = new RecurlyBillingInfo(account);
billingInfo.FirstName = account.FirstName;
billingInfo.LastName = account.LastName;
billingInfo.Address1 = "123 Test St";
billingInfo.City = "San Francsico";
billingInfo.State = "CA";
billingInfo.Country = "US";
billingInfo.PostalCode = "94105";
billingInfo.CreditCard.ExpirationMonth = DateTime.Now.Month;
billingInfo.CreditCard.ExpirationYear = DateTime.Now.Year + 1;
billingInfo.CreditCard.Number = "4111-1111-1111-1111";
billingInfo.CreditCard.VerificationValue = "123";
billingInfo.Update();

Parameters

first_name

First name on the credit card/billing address

last_name

Last name on the credit card/billing address

address1

Street address line 1. This may be optional or required, depending on your address verification settings.

address2

Street address line 2

city

City

state

2-letter state or province code

country

2-letter ISO country code

zip

Zip code or postal code

phone

Phone number for the billing address

ip_address

User's IP address when providing billing information. Optional but very highly recommended for fraud detection.

vat_number

Customer's VAT Number

Credit card parameters

credit_card[number]

14-19 digit credit card number. Most US and EU card numbers are 15-16 digits, some Chinese cards may be 19 digits. Spaces and dashes will automatically be removed by Recurly.

credit_card[verification_value]

3 or 4 digit Card Verification Value (CVV) found on the security panel

credit_card[month]

Expiration month (1 - 12)

credit_card[year]

Expiration year, 4 digits

CVV Codes Recurly uses the CVV/security/verification code when authorizing or updating a credit card number if supported by the payment gateway and the given credit card type. However, this value is never stored or persisted -- it is used for the initial transaction only. Your application should never store or log the CVV value for a credit card. Subsequent transactions are more likely to be accepted by the account's credit's card if the first transaction is authorized using the CVV code.

Credit Card Type The credit card type is set by Recurly. You do not need to prompt for credit card type. Values we return are: visa, master, american_express, discover, diners_club, jcb, maestro, laser, and Unknown.

Address Fields Recurly requires different address fields depending on the requirements you configure in the Configuration tab. If you do not want to collect address information, set the address requirements to 'None'. To maximize the acceptance of Address Validation (AVS), Recurly suggests collecting Street Address and Zip/Postal Codes at a minimum. The other address fields are nice to have but do not enhance validation.

IP Address On the hosted forms, Recurly records the user's IP address. When submitting transactions via the API, you are encouraged to submit the user's IP address. If your payment gateway supports IP address information, Recurly will pass along the IP address. Some gateways are able to filter out fraudulent transactions using the IP address.

Get account's billing information

Returns only the account's current billing information.

Code examples

PHP

1

$billing_info = RecurlyBillingInfo::getBillingInfo($acct->account_code);

Ruby

1

billing_info = Recurly::BillingInfo.find(user.id)

Python

1

billing_info = recurly.accounts.billing_info(account_code=self.account_code)

C#

1

RecurlyBillingInfo billingInfo = RecurlyBillingInfo.Get(accountCode);

Clearing an account's billing information

To permanently clear an account's billing information from Recurly, you may issue a DELETE request on the billing info. If the account has a subscription, the renewal will go into past due unless you update the billing info before the renewal occurs.

Automatic deleting of billing information

An account's billing information will be automatically deleted in the following scenarios:

• Account is marked as closed in Recurly
• Account has no transactions for over a year since the account's billing information was last updated
• Your Recurly account is closed

Code examples

PHP

1
2

$billing_info = RecurlyBillingInfo::getBillingInfo($acct->account_code);
$billing_info->clear();

Ruby

1
2

billing_info = Recurly::BillingInfo.find(user.id)
billing_info.destroy unless billing_info.nil?

Python

1

recurly.accounts.billing_info.delete(account_code=self.account_code)

C#

1
2

RecurlyBillingInfo billingInfo = RecurlyBillingInfo.Get(accountCode);
billingInfo.ClearBillingInfo();