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    

Auth and Capture

Authorization and Capture will allow merchants to first authorize a subscriber’s credit card to ensure it is valid and that sufficient funds are available and then, collect the funds for the amount due at a later time.

Auth and Capture

This functionality is available via API and select client libraries. The 3 related API endpoints are:

  • v2/purchases/authorize
  • v2/purchases/capture
  • v2/purchases/cancel

To capture or cancel an authorize transaction, use /capture or /cancel endpoints and include the transaction UUID from the original authorize transaction:

  • v2/purchases/transaction-uuid-<AUTHORIZED-TXN-UUID-HERE>/capture
  • v2/purchases/transaction-uuid-<AUTHORIZED-TXN-UUID-HERE>/cancel

Definitions:

  • Authorize: When you authorize a subscriber's credit card, we check with the subscriber's bank to see if the credit card is legitimate and has sufficient funds for the amount you authorized. If the subscriber's bank approves, a hold is placed on the funds in the subscriber's account but no money has moved, yet.
  • Capture: In order to actually move money from the subscriber's account, you have to issue a capture request on the original authorization to collect ("capture") the funds.
  • Cancel: If you choose not to capture the funds from the subscriber's account, you can explicitly cancel the authorization to release the hold on those funds.

Authorizing first and capturing funds later allows you to (for example):

  • Authorize the amount first but only capture the funds once you've shipped the physical goods.
  • Perform a manual fraud review before capturing the funds and fulfilling the order.
  • Authorize the amount at the start of a free trial and then capture the funds at start of the subscription.

Keep in mind:

  • You can only capture an authorization once.
  • You must capture all the line items on an invoice, and for the full amount of the authorization.
  • Gift cards and coupons will be redeemed and marked as used at the time of authorization.
  • Authorizations automatically expire after a period of time if they are not captured. The length of time varies by card brand and gateway, but usually it is within 7-10 days. If you wait too long to capture an authorization, the gateway may have already canceled the authorization.
  • If an authorization has already been captured, Recurly will return an error message via the API.
  • If an authorization has already been canceled, Recurly will return an error message via the API. In this case, you can either: submit a new authorization, or initiate a transaction request.

Auth & Capture is currently supported for the following gateways:

  • Braintree
  • Stripe
  • Other gateways will be added according to merchant demand.

Pricing:

There are no per transaction fees for authorizations. Merchants will only be charged for captures.

The following is not supported at this time:

  • "Partial captures": partially capturing an authorization (e.g. only capturing $5 of a $10 authorization).
  • "Multiple captures": partially capturing an authorization multiple times (e.g. capturing $2 first, then $8, of a $10 authorization). Capture requests must capture all line items on an invoice.
  • Capturing more than the amount authorized (e.g. capturing $11.50 of a $10 authorization).
  • Also note: Recurly does not automatically authorize your subscribers' cards in advance of recurring subscription renewals.

Workaround for multiple captures:

  • Merchants can capture the full authorization amount, and then refund individual line items in separate refund transaction requests.
  • Merchants can cancel the initial authorization, and then initiate transaction requests for individual line items as separate transactions.

Other limitations:

  • Recurly will not automatically cancel authorizations. You will need to explicitly cancel authorizations so that there are not long holds on customers' accounts. Note: it is best industry practice for merchants to explicitly cancel authorizations and not rely on authorizations to be expired by the gateways.
  • Recurly will not inform merchants when authorizations have been canceled or expired upstream, i.e. by the gateway. This information is not always available from the gateway.
  • Delayed capture: Recurly does not support delaying or customizing the timing of captures, i.e. captures are immediately initiated when the API request is received.
  • Captures cannot be canceled or voided. The transaction would have to be refunded upon success.
  • Subscriptions with a future start date (free trial) longer than 7 days is not supported on Stripe.
  • Auth and Capture is only supported via Recurly’s API and select client libraries.
  • Auth and Capture does not fully support 3rd party integrations such as Xero or QB (coming soon).

Support:

To enable this feature, please contact Recurly Support.

Auth and Capture flow: