Recurly

Transactions API

List transactions

Returns a list of all the transactions.

GET https://:subdomain.recurly.com/v2/transactions

Query Parameters

Parameter Default Description
state all The state of transactions to return: "successful", "failed", or "voided".
type all The type of transactions to return: "authorization", "refund", or "purchase".
cursor Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page 50 Number of records to return per page, up to a maximum of 200.

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 4725
Link: <https://your-subdomain.recurly.com/v2/transactions>; rel="start",
  <https://your-subdomain.recurly.com/v2/transactions?cursor=1318389123>; rel="next"
ETag: "54f8de3d50cd190d9e765598f9711489"
<?xml version="1.0" encoding="UTF-8"?>
<transactions type="array">
  <transaction href="https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" type="credit_card">
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde"/>
    <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>
    <action>purchase</action>
    <amount_in_cents type="integer">1000</amount_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <currency>USD</currency>
    <status>success</status>
    <reference nil="nil"></reference>
    <test type="boolean">true</test>
    <voidable type="boolean">true</voidable>
    <refundable type="boolean">true</refundable>
    <cvv_result code="" nil="nil"></cvv_result>
    <avs_result code="" nil="nil"></avs_result>
    <avs_result_street nil="nil"></avs_result_street>
    <avs_result_postal nil="nil"></avs_result_postal>
    <created_at type="datetime">2011-06-27T12:34:56Z</created_at>
    <details>
      <account>
        <account_code>verena100</account_code>
        <first_name>Verena</first_name>
        <last_name>Example</last_name>
        <company nil="nil"></company>
        <email>verena@test.com</email>
        <billing_info type="credit_card">
          <first_name nil="nil"></first_name>
          <last_name nil="nil"></last_name>
          <address1 nil="nil"></address1>
          <address2 nil="nil"></address2>
          <city nil="nil"></city>
          <state nil="nil"></state>
          <zip nil="nil"></zip>
          <country nil="nil"></country>
          <phone nil="nil"></phone>
          <vat_number nil="nil"></vat_number>
          <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>
      </account>
    </details>
    <a name="refund" href="http://api.test.host/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" method="delete"/>
  </transaction>
  <!-- Continued... -->
</transactions>

$transactions = Recurly_TransactionList::get();
foreach ($transactions as $transaction) {
  print "Transaction: $transaction\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
Recurly::Transaction.find_each do |transaction|
  puts "Transaction: #{transaction.inspect}"
end
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
#client version <= 2.1.5
transactions = Transaction.all()
while transactions:
    for transaction in transactions:
        print 'Transaction: %s' % transaction
    try:
        transactions = transactions.next_page()
    except PageError:
        transactions = ()

#client version 2.1.6+
for transaction in Transaction.all():
    print 'Transaction: %s' % transaction

List an account's transactions

Returns a list of transactions for an account.

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

Query Parameters

Parameter Default Description
state all The state of transactions to return: "successful", "failed", or "voided".
type all The type of transactions to return: "authorization", "refund", or "purchase".
cursor Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page 50 Number of records to return per page, up to a maximum of 200.

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 4725
Link: <https://your-subdomain.recurly.com/v2/account/100/transactions>; rel="start",
  <https://your-subdomain.recurly.com/v2/account/100/transactions?cursor=1318389123>; rel="next"
ETag: "54f8de3d50cd190d9e765598f9711489"
<?xml version="1.0" encoding="UTF-8"?>
<transactions type="array">
  <transaction href="https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" type="credit_card">
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde"/>
    <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>
    <action>purchase</action>
    <amount_in_cents type="integer">1000</amount_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <currency>USD</currency>
    <status>success</status>
    <reference nil="nil"></reference>
    <test type="boolean">true</test>
    <voidable type="boolean">true</voidable>
    <refundable type="boolean">true</refundable>
    <cvv_result code="" nil="nil"></cvv_result>
    <avs_result code="" nil="nil"></avs_result>
    <avs_result_street nil="nil"></avs_result_street>
    <avs_result_postal nil="nil"></avs_result_postal>
    <created_at type="datetime">2011-06-27T12:34:56Z</created_at>
    <details>
      <account>
        <account_code>verena100</account_code>
        <first_name>Verena</first_name>
        <last_name>Example</last_name>
        <company nil="nil"></company>
        <email>verena@test.com</email>
        <billing_info type="credit_card">
          <first_name nil="nil"></first_name>
          <last_name nil="nil"></last_name>
          <address1 nil="nil"></address1>
          <address2 nil="nil"></address2>
          <city nil="nil"></city>
          <state nil="nil"></state>
          <zip nil="nil"></zip>
          <country nil="nil"></country>
          <phone nil="nil"></phone>
          <vat_number nil="nil"></vat_number>
          <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>
      </account>
    </details>
    <a name="refund" href="http://api.test.host/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" method="delete"/>
  </transaction>
  <!-- Continued... -->
</transactions>

$transactions = Recurly_TransactionList::getForAccount('1');
foreach ($transactions as $transaction) {
  print "Transaction: $transaction\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
account = Recurly::Account.find('1')
account.transactions.find_each do |transaction|
  puts "Transaction: #{transaction.inspect}"
end
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
#client version <= 2.1.5
account = Account.get('1')
transactions = account.transactions()
while transactions:
    for transaction in transactions:
        print 'Transaction: %s' % transaction
    try:
        transactions = transactions.next_page()
    except PageError:
        transactions = ()

#client version 2.1.6+
account = Account.get('1')
for transaction in account.transactions():
    print 'Transaction: %s' % transaction

Lookup transaction

Lists details for an individual transaction.

GET https://:subdomain.recurly.com/v2/transactions/:id

The details section contains the account and billing information at the time the transaction was submitted. It may not reflect the latest account information. A transaction_error section be included if the transaction failed. Please see transaction error codes for more details.

Transaction Attributes

Attributes Description
uuid Unique transaction ID
action "purchase", "authorization", or "refund"
currency 3-letter currency for the transaction
amount_in_cents Total transaction amount in cents
tax_in_cents Amount of tax or VAT within the transaction, in cents
status "success", "failed", or "void"
reference Transaction reference from your payment gateway
source Source of the transaction. Possible values: transaction for one-time transactions, subscription for subscriptions, billing_info for updating billing info.
test True if test transaction
voidable True if the transaction may be voidable, accuracy depends on your gateway
refundable True if the transaction may be refunded
cvv_result CVV result, if applicable
avs_result AVS result, if applicable
avs_result_street AVS result for the street address, line 1
avs_result_postal AVS result for the postal code
created_at Date the transaction took place
details Nested account and billing information submitted at the time of the transaction. When writing a client library, do not map these directly to Account or Billing Info objects.

Example

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
ETag: "a4b0568a2278bc591ceb64b31547eb78"
<?xml version="1.0" encoding="UTF-8"?>
<transaction href="https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
  <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde"/>
  <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>
  <action>purchase</action>
  <amount_in_cents type="integer">1000</amount_in_cents>
  <tax_in_cents type="integer">0</tax_in_cents>
  <currency>USD</currency>
  <status>success</status>
  <source>transaction</source>
  <reference nil="nil"></reference>
  <test type="boolean">true</test>
  <voidable type="boolean">true</voidable>
  <refundable type="boolean">true</refundable>
  <cvv_result code="" nil="nil"></cvv_result>
  <avs_result code="" nil="nil"></avs_result>
  <avs_result_street nil="nil"></avs_result_street>
  <avs_result_postal nil="nil"></avs_result_postal>
  <created_at type="datetime">2011-06-27T12:34:56Z</created_at>
  <details>
    <account>
      <account_code>verena100</account_code>
      <first_name>Verena</first_name>
      <last_name>Example</last_name>
      <company nil="nil"></company>
      <email>verena@test.com</email>
      <billing_info type="credit_card">
        <first_name nil="nil"></first_name>
        <last_name nil="nil"></last_name>
        <address1 nil="nil"></address1>
        <address2 nil="nil"></address2>
        <city nil="nil"></city>
        <state nil="nil"></state>
        <zip nil="nil"></zip>
        <country nil="nil"></country>
        <phone nil="nil"></phone>
        <vat_number nil="nil"></vat_number>
        <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>
    </account>
  </details>
  <a name="refund" href="http://api.test.host/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" method="delete"/>
</transaction>

try {
  $transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');
  print "Transaction: $transaction\n";
} catch (Recurly_NotFoundError $e) {
  print "Transaction not found\n";
}

transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')

transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')

Create transaction

The Recurly API provides a shortcut for creating an invoice, charge, and optionally account, and processing the payment immediately. When creating an account all of the required account attributes must be supplied. When charging an existing account only the account_code must be supplied.

POST https://:subdomain.recurly.com/v2/transactions

Transaction Attributes

Transaction Parameters Description
account Nested attributes for the account. Required
amount_in_cents Amount of the transaction in cents. Max 10000000. Required
currency 3-letter currency for the transaction Required
description A description for the transaction. Description is added to the invoiced charge, and not the transaction object
Account Parameters Description
account_code A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters.Required
username Username, ignore if you do not use usernames
email Email address
first_name First name. Max of 50 characters.
last_name Last name. Max of 50 characters.
company_name Company name. Max of 50 characters.
accept_language An ISO 639-1 language code from the user's browser, indicating their preferred language and locale
billing_info Nested billing information, if not present, the stored billing information will be used
Billing Info Parameters Description
first_name First name. Max 50 characters. Required
last_name Last name. Max 50 characters.Required
company Company name. Max of 50 characters.
address1 Address line 1, recommended for address validation. Max 50 characters. Recommended
address2 Address line 2. Max 50 characters.
city City. Max 50 characters.
state State or Province, 2-letters preferred
country Country, 2-letter ISO code Strongly Recommended
zip Zip or postal code, recommended for address validation Recommended
phone Phone number
vat_number Customer's VAT Number
ip_address Customer's IP address when updating their billing information Strongly Recommended
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

Using stored billing info

You may create a transaction without specifying billing information if an account already has stored billing information.

Example with stored billing info

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<transaction>
  <amount_in_cents>100</amount_in_cents>
  <currency>USD</currency>
  <account>
    <account_code>1</account_code>
  </account>
</transaction>

$transaction = new Recurly_Transaction();
$transaction->amount_in_cents = 100; // $1.00
$transaction->currency = 'USD';

$transaction->account = new Recurly_Account();
$transaction->account->account_code = '1';

$transaction->create();

transaction = account.transactions.create(
  :amount_in_cents => 1_00,
  :currency        => 'USD'.
  :account         => { :account_code => '1' }
)

transaction = Transaction(
  amount_in_cents=100,
  currency='USD',
  account=Account(account_code='1')
)
transaction.save()

// TODO

Example with new billing info

After a successful transaction, the billing information will be saved with the account for future purchases. If the account already has stored billing info, the billing info from the last transaction will be saved in its place.

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<transaction>
  <amount_in_cents>1000</amount_in_cents>
  <currency>USD</currency>
  <account>
    <account_code>1</account_code>
    <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>
  </account>
</transaction>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f
<?xml version="1.0" encoding="UTF-8"?>
<transaction href="https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" type="credit_card">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
  <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>
  <action>purchase</action>
  <amount_in_cents type="integer">1000</amount_in_cents>
  <tax_in_cents type="integer">0</tax_in_cents>
  <currency>USD</currency>
  <status>success</status>
  <reference nil="nil"></reference>
  <test type="boolean">true</test>
  <voidable type="boolean">true</voidable>
  <refundable type="boolean">true</refundable>
  <cvv_result code="" nil="nil"></cvv_result>
  <avs_result code="" nil="nil"></avs_result>
  <avs_result_street nil="nil"></avs_result_street>
  <avs_result_postal nil="nil"></avs_result_postal>
  <created_at type="datetime">2011-06-27T12:34:56Z</created_at>
  <details>
    <account>
      <account_code>verena100</account_code>
      <first_name>Verena</first_name>
      <last_name>Example</last_name>
      <company nil="nil"></company>
      <email>verena@test.com</email>
      <billing_info type="credit_card">
        <first_name nil="nil"></first_name>
        <last_name nil="nil"></last_name>
        <address1 nil="nil"></address1>
        <address2 nil="nil"></address2>
        <city nil="nil"></city>
        <state nil="nil"></state>
        <zip nil="nil"></zip>
        <country nil="nil"></country>
        <phone nil="nil"></phone>
        <vat_number nil="nil"></vat_number>
        <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>
    </account>
  </details>
  <a name="refund" href="http://api.test.host/v2/transactions/a13acd8fe4294916b79aec87b7ea441f" method="delete"/>
</transaction>

$transaction = new Recurly_Transaction();
$transaction->amount_in_cents = 1000; // $10.00.
$transaction->currency = 'USD';

$account = new Recurly_Account();
$account->account_code = '1';

$billing_info = new Recurly_BillingInfo();
$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;

$account->billing_info = $billing_info;
$transaction->account = $account;

$transaction->create();

transaction = Recurly::Transaction.create(
  :amount_in_cents => 10_00,
  :currency        => 'USD',
  :account         => {
    :account_code => '1',
    :billing_info => {
      :first_name         => 'Verena',
      :last_name          => 'Example',
      :number             => '4111-1111-1111-1111',
      :verification_value => '123',
      :month              => 11,
      :year               => 2015
    }
  }
)

transaction = Transaction(
  amount_in_cents=1000,
  currency='USD',
  account=Account(
    account_code=account_code,
    billing_info=BillingInfo(
      first_name='Verena',
      last_name='Example',
      number='4111-1111-1111-1111',
      verification_value='123',
      year=2015',
      month=11
    )
  )
)
transaction.save()

Refund transactions

Refund or void a previous, successful transaction.

DELETE https://:subdomain.recurly.com/v2/transactions/:id

A transaction can refunded if it has settled successfully. It can be refunded for any amount equal to or less than the original amount. Please note, some payment gateways do not allow the same credit card to be partially refunded on the same day as the original purchase.

A link to the refund action can be found as an anchor node in the body of a transaction's XML.

Query Parameters

Parameter Description
amount_in_cents Amount to refund in cents. Defaults to full amount.

Partial refunds

If the transaction has not settled and you attempt a partial refund, the request will fail. Please wait until the transaction has settled (typically 24 hours) before performing a partial refund. This advice varies depending on when your payment gateway settles the transaction.

Partial Refund Example

$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');
$transaction->refund(1000); // Refund $10.00.

transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')
transaction.refund(10_00)

transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')
transaction.refund(amount_in_cents=1000)

// TODO

Full refunds

If the transaction has not settled and you perform a full refund, the transaction will be voided instead. Voided transactions typically do not show up on the customer's card statement. If the transaction has settled, a refund will be performed.

Full Refund Example

$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');
$transaction->refund();

transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')
transaction.refund()

transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')
transaction.refund()