Recurly

Billing Info API

Lookup an account's billing info

Returns only the account's current billing information.

GET https://:subdomain.recurly.com/v2/accounts/:account_code/billing_info

Attributes

Attribute Description
first_name First name
last_name Last name
address1 Address line 1
address2 Address line 2
city City
state State
country Country, 2-letter ISO code
zip Zip or postal code
phone Phone number
vat_number Customer's VAT Number
ip_address Customer's IP address when updating their billing information
ip_address_country Country of IP address, if known by Recurly
Credit Card Attributes Description
first_six Credit card number, first six digits
last_four Credit card number, last four digits
card_type Visa, MasterCard, American Express, Discover, JCB, etc
month Expiration month
year Expiration year
PayPal Attribute Description
billing_agreement_id PayPal Billing Agreement ID

Example

Response with credit card info

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<billing_info href="http://api.test.host/v2/accounts/1/billing_info" type="credit_card">
  <account href="http://api.test.host/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"></phone>
  <vat_number>US1234567890</vat_number>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country>US</ip_address_country>
  <card_type>Visa</card_type>
  <year type="integer">2015</year>
  <month type="integer">11</month>
  <first_six>411111</first_six>
  <last_four>1111</last_four>
</billing_info>

Response with PayPal info

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<billing_info href="http://api.test.host/v2/accounts/1/billing_info" type="paypal">
  <account href="http://api.test.host/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"></phone>
  <vat_number>US1234567890</vat_number>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country>US</ip_address_country>
  <billing_agreement_id>B-1234567890</billing_agreement_id>
</billing_info>

try {
  $billing_info = Recurly_BillingInfo::get('1');
  print "Billing Info: $billing_info\n";
} catch (Recurly_NotFoundError $e) {
  print "No billing information.\n";
}

account = Recurly::Account.find('1')
billing_info = account.billing_info

account = Account.get('1')
billing_info = account.billing_info

Update an account's billing info

Returns only the account's current billing information.

PUT https://:subdomain.recurly.com/v2/accounts/:account_code/billing_info

When billing information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the billing information.

If you want to create an account at the same time, you should use the Account API end-point instead and include billing info with your request.

Please note: this API end-point may be used to import billing information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated billing information.

Billing Information Attributes

Billing Address Parameter Description
first_name First name Required
last_name Last name Required
address1 Address line 1, recommended for address validation
address2 Address line 2
city City
state State
country Country, 2-letter ISO code Strongly Recommended
zip Zip or postal code, recommended for address validation
phone Phone number
vat_number Customer's VAT Number
ip_address Customer's IP address when updating their billing information Strongly Recommended
Credit Card Parameter Description
number Credit card number, spaces and dashes are accepted Required
month Expiration month Required
year Expiration year Required
verification_value Security code or CVV, 3-4 digits Strongly Recommended

Example

Request

Location: https://your-subdomain.recurly.com/accounts/1/billing_info
Accept: application/xml
Content-Type: application/xml; charset=utf-8
<billing_info>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <number>4111-1111-1111-1111</number>
  <verification_value>123</verification_value>
  <month>11</month>
  <year>2015</year>
</billing_info>

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<billing_info href="http://api.test.host/v2/accounts/1/billing_info" type="credit_card">
  <account href="http://api.test.host/v2/accounts/1"/>
  <first_name>Verena</first_name>
  <last_name>Example</last_name>
  <company nil="nil"></company>
  <address1>123 Main St.</address1>
  <address2 nil="nil"></address2>
  <city>San Francisco</city>
  <state>CA</state>
  <zip>94105</zip>
  <country>US</country>
  <phone nil="nil"></phone>
  <vat_number>US1234567890</vat_number>
  <ip_address>127.0.0.1</ip_address>
  <ip_address_country>US</ip_address_country>
  <card_type>Visa</card_type>
  <year type="integer">2015</year>
  <month type="integer">11</month>
  <first_six>411111</first_six>
  <last_four>1111</last_four>
</billing_info>

$billing_info = new Recurly_BillingInfo();
$billing_info->account_code = '1';
$billing_info->first_name = 'Verena';
$billing_info->last_name = 'Example';
$billing_info->number = '4111-1111-1111-1111';
$billing_info->verification_value = '123';
$billing_info->month = 11;
$billing_info->year = 2015;
$billing_info->update();

account = Recurly::Account.find('1')
account.billing_info = {
  :first_name         => 'Verena',
  :last_name          => 'Example',
  :number             => '4111-1111-1111-1111',
  :verification_value => '123',
  :month              => 11,
  :year               => 2015
}
account.billing_info.save

account = Account.get('1')
billing_info = account.billing_info
billing_info.first_name = 'Verena'
billing_info.last_name = 'Example'
billing_info.number = '4111-1111-1111-1111'
billing_info.verification_value = '123'
billing_info.month = 11
billing_info.year = 2015
billing_info.save()

Clear an account's billing info

You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into past due unless you update the billing info before the renewal occurs.

DELETE https://:subdomain.recurly.com/v2/accounts/:account_code/billing_info

Example

Response

Status: 204 No Content
$billing_info = Recurly_BillingInfo::get('1');
$billing_info->delete();

// Or, in a single API request:
// Recurly_BillingInfo::deleteForAccount('1');

account = Recurly::Account.find('1')
if billing_info = account.billing_info
  billing_info.destroy
end

account = Account.get('1')
billing_info = account.billing_info
if billing_info
  billing_info.delete()