The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Transactions

Purchasing information is sent to your payment gateway in an action called a transaction. This includes the customer's billing information and the amount of money to be charged, voided, or refunded.

Your transactions dashboard provides an overview of all transactions processed through Recurly. Transactions can be searched by transaction Universally Unique Identifier (UUID), customer first name, last name, account code, the last four digits of the card number, card type, payment gateway reference ID, transaction amount or currency. The filters on this view allow you to group transactions by type and response:

Payments

Purchases processed through Recurly.

Refunds

Refunds processed on a previously-successful Recurly transaction.

Verifications

$0 or $1 transactions used to verify billing information, voided immediately.

Successful

Transactions approved by the payment gateway.

Declined

Transactions declined by the payment gateway.

Voided

Transactions voided before the payment settled.

Chargeback

Only used for ACH beta, indicates a chargeback ACH payment.

Transaction Search

You may search for a transaction on any of the following fields:

  • Account code
  • Company name
  • First name
  • Last name
  • Email address
  • Username
  • Amount
  • First six of credit card
  • Last four of credit card
  • Transaction reference ID
  • Transaction unique ID (UUID)

Creating a Transaction

Transactions are automatically created when an invoice is set to be processed. A transaction is created either as the result of a subscription action (creation, renewal, modification) or a charge being created and invoiced on the account. To reduce per transaction gateway fees and separate bank charges for end-customers, it is recommended to use the Purchase endpoint for your subscription and one-time charge billing. This particular endpoint supports billing for any combination of subscriptions and one-time charges in your checkout, and will sum all line-item charges into a single transaction that gets sent to your payment gateway.

Minimum Purchase Amount

To save in merchant fees, Recurly will not send transactions under $0.03 to your payment gateway, but will instead immediately mark the invoice as paid. Some payment gateways also have minimum purchase amounts, usually $0.30-0.50.

Structure

General Details

The transaction type (payment, refund, authorization, etc.), status (success, declined, voided), amount of the transaction, and the customer's billing information including card type and address information (if collected).

Fraud Details

Typically just informative, indicating the type of address checks performed by the payment gateway.

Additional Details

Useful in tracking the reason for a transaction decline. This section will provide any error codes or messages returned by the payment gateway. It will also contain a reference number which can be used for finding the transaction inside a third-party payment gateway virtual terminal.

Settling Transactions

At time of purchase, your payment gateway connects to their credit card processors to verify the customer's billing information and ensure that funds are available. When the response is a success the funds are held and the transaction amount deducted from the customer's bank account balance. At the end of the day, the payment gateway will submit these transactions for finalized processing and the funds are released to the merchant. The difference between a settled and unsettled transaction will impact how voids, refunds, and partial refunds occur.

Verification

When billing information is added or updated to an account Recurly issues a $1.00 authorization charge (Or $0.00 verification, for gateways that support a feature called Zero Dollar Authorizations) to verify the customer's billing information. Once Recurly receives a success/decline response from the gateway, this charge is voided. Subscription plans with trials will also process a verification charge to verify the customer's billing data at signup.

Refunds and Voids

An unsettled transaction can be voided—stopping the transaction from processing and removing it from the customer's account. Once a transaction has been settled it can only be refunded. Because payment gateways have different processing times for settling transactions, Recurly will automatically attempt a void before processing a refund. Partial refunds can only be issued on a settled transaction, so please wait 24 hours after an initial transaction has processed before attempting a partial refund.

A voided transaction will typically disappear from a customer's credit/debit account statement within 24 hours, while a refund may take 3 to 5 business days to appear on a customer's credit/debit account statement.

A refund will always be issued to the card (or bank account for ACH) used on the original payment.

To refund/void a transaction or invoice:

  1. Open the customer's account and click on either the transaction you'd like to refund in the Transactions section or the invoice you would like to refund in the Invoices section of their account.

  2. Transactions will take you to the Transaction Details page. Click the Refund Transaction button in the upper right corner of the page. Invoices will take you to the Invoice Details page. Click the Refund Invoice button in the left sidebar of the page.

  3. Select the specific charge line items you would like to refund, with the option to prorate subscription charges or select specific quantities. If you prefer to refund a custom amount, click on "Refund a partial item or specific amount?". If you are entering a custom refund amount, it cannot exceed the amount of the transaction. Note that an unsettled transaction can only be voided, which requires a full refund request.

  4. If there are credit line items on the invoice, and you are doing a partial refund, you can chose to refund that amount by returning credit back to the account first and then creating a transaction with any remaining non-credit amount, or you can choose to refund by "Transaction first" and issue money back to the customer before any credit is put back on their account. By default, refunds put credit back on the customer's account first. You can change this setting to "Transaction first" using the radio buttons at the top of the page.

  5. Click Preview Refund and review your refund. This page will detail the discounts and taxes being refunded, as well as show any credit being returned to the account.

  6. When you are ready, click Refund Charges to finalize your refund. This will create a refund invoice and transaction.

Learn more about invoices for voided and refunded transactions in our Invoices section.

Fraud Velocity Checks

All transactions are passed through a simple fraud velocity filter before being passed on to the payment gateway. This doesn't guarantee that no fraud will occur, but it will reduce the possibility of large volumes of fraudulent transactions. Please note that the following limits only apply to sites in production mode.

Fraud Velocity checks can be enabled based on the following criteria:

  • Limits on transactions
  • New subscriptions
  • Updates to Billing Information

If any of these limits are exceeded, transactions will fail with the "fraud_velocity" error code, and your customer will be notified to contact support.

Some fraud velocity filters may be enforced using IP based rules, you must provide your customer's actual IP address. If no address is provided for the transaction, or if a local address is provided, such as "127.x.x.x" or "10.x.x.x", we cannot accurately detect fraudulent behavior.

An IP address whitelist can be defined in your site settings. If you'd like to disable fraud velocity checks for your site, please contact support.

If you are looking for more custom fraud management, learn more about Recurly's Fraud Management solution.

CSV Export

Your transactions dashboard allows a full export of your customer transaction data in CSV format. This export contains the following columns: account_code, name, transaction_id, type, amount, tax_amount, currency, date, status, message, test, cc_type, cvv_result, avs_result, avs_result_postal, avs_result_street, reference, approval_code, description, state, country, ip_address_country, original_transaction_id, invoice_id, subscription_id, po_number, collection_method, transaction_gateway_type, modified_at, origin, gateway_error_codes.

Transactions


Purchasing information is sent to your payment gateway in an action called a transaction. This includes the customer's billing information and the amount of money to be charged, voided, or refunded.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.