This guide walks you through using Recurly's Purchases endpoint to process an eCommerce transaction without storing the customer's payment details on file. You'll learn which gateways and payment methods support this behavior, how to structure the request, and what to expect in the response — so you can build guest checkout, gift-purchase, and one-off payment flows without disturbing a subscriber's saved payment method.

1Definition 2Key concepts 3Integration guide 4Best practices 5Error handling 6Webhooks 7Testing 8What's next

Prerequisites

Familiarity with Recurly's API and basic REST concepts
Completed the Quickstart Guide
A gateway and payment method combination where Recurly supports eCommerce transactions

Limitations

This behavior is currently limited to specific gateway and payment method combinations: GCash when using dLocal (requires non-storage), and credit cards when using Adyen
For credit card payments on Adyen, all customer-initiated features are supported, including Level 2 and Level 3 processing, dynamic descriptors, Adyen's fraud ID usage, Kount, and 3-D Secure. For specific questions, contact [email protected] or your CSM
Purchase and separate authorize-and-capture are supported for cards only. GCash requires the Purchases endpoint only
If you have a gateway and payment method combination that isn't listed here, submit a feature request

Definition

Creating a purchase means generating a new customer account alongside a transaction in a single, consolidated call to the Purchases endpoint — bundling everything a checkout needs into one request. By default, Recurly stores the billing details you provide so they're available for future transactions. Setting store_billing_info to false tells Recurly to process the transaction without keeping that payment method on file.

Key concepts

eCommerce transaction: An online transaction where the customer is in session in your checkout flow, making a one-time purchase — for physical or digital items, for example — rather than signing up for a subscription.
Billing info and payment method storage: The ability and practice of storing a payment method instrument on file in Recurly for future use.

Common use cases

Guest checkout — a logged-in subscriber wants to buy a one-off item (merch, add-on, upsell) with a different card than the one on file, without disturbing the subscription's default payment method
Time-based subscription models — a subscription model where customers make one-time purchases and must return to session after a period of time
Single-use APMs by design — payment methods like GCash are inherently redirect- or voucher-based with no vaulting concept, so you still need a way to complete the purchase
Gift subscriptions — a customer buys a subscription or one-time item for someone else and doesn't want their card to become the recipient's stored payment method. This appears as a line item via the API rather than a plan code with a set payment method
Paying down an outstanding balance — an AP team pays down an invoice or past-due balance with a corporate card that isn't meant to become the account's recurring payment method
Regional data residency rules — jurisdictions that restrict cross-border card storage, where one-time processing sidesteps the residency requirement entirely
Short trials — a customer wants to test a purchase flow or make a small one-off buy without risking it silently becoming the subscription's payment method on the next renewal
Separate authorization and capture — your business model matches any of the above use cases, but you want to authorize now and capture manually later

Integration guide

Requirements

You must have the Enable store_billing_info on purchase requests feature flag enabled — contact [email protected] to have it turned on
You must be using the Purchases or Purchases/Authorize endpoints. GCash only supports the Purchases endpoint, while cards can use either
You must pass the billing_info.store_billing_info field set to false
You must be using a supported gateway and payment method — see Limitations above

Parameter	Type	Description
`billing_info.store_billing_info`	Boolean. Default: `true`	An identifier for the intent to store the provided payment method on the transaction. Certain payment methods require `true` or `false` — see your respective payment method integration guides for details.

Generate an eCommerce request

Use a supported client library, or set store_billing_info to false directly in your code, to specify an eCommerce transaction where Recurly should not store the billing information provided.

Send a request to the create Purchases endpoint, including:

Customer account data (code, name, billing info, phone number, email address, and so on)
Line items (no plan codes)
If applicable, the payment method type — unnecessary for cards with Adyen, but GCash requires passing the type field as gcash
The store billing info indicator set to false

{
  "currency": "USD",
  "account": {
      "code": "account-code",
      "billing_info": {
          "first_name": "John",
          "last_name": "Doe",
          "address": {
              "street1": "123",
              "city": "Chicago",
              "region": "IL",
              "postal_code": "60601",
              "country": "US"
          },
          "number": "4111111111111111",
          "month": "03",
          "year": "2030",
          "cvv": "737",
          "store_billing_info": false
      }
  },
  "gateway_code": "gateway-code",
  "line_items": [
      {
          "unit_amount": "10.00",
          "quantity": 2,
          "description": "CIT Physical Charge + Tax",
          "type": "charge",
          "tax_code": "physical",
          "product_code": "1001"
      }
  ],
  "shipping": {
      "address": {
          "first_name": "John",
          "last_name": "Doe",
          "phone": "4567890123",
          "street1": "201 main St",
          "city": "Chicago",
          "region": "IL",
          "postal_code": "45678",
          "country": "US"
      }
  }
}

TipMany more parameters are available. See the Create Purchase reference to learn more.

Process the purchase response

A successful purchase returns an InvoiceCollection, which contains any charge or credit invoices generated by the request.

If the purchase fails, you'll receive an error response indicating what went wrong. Credit card purchases return an Approved transaction with a Paid invoice. If you're using separate authorization and capture, the transaction returns as Approved and the invoice remains Pending.

Verify and finish

After a successful purchase, confirm the details through the Recurly Admin UI or by calling Recurly's API to list details on the purchase, invoice, and account.

NoteThe account won't have billing info if nothing was stored previously.

Listen for webhooks

After a successful purchase, several webhooks fire so you can enable access to features in your environment as needed.

[TODO: List the specific webhook events this integration should subscribe to]

Best practices

Use separate authorization and capture when there's a genuine fulfillment delay — don't capture until goods ship, to avoid refund churn and reduce chargeback exposure
Respect authorization validity windows for your card scheme and gateway; don't let a stale authorization expire before capture. As a general rule this ranges from 7 to 30 days, but confirm specifics with your gateway
Use 3-D Secure wherever it's required, especially where Strong Customer Authentication (SCA) is mandated. eCommerce transactions on Recurly are customer-initiated, so the usual requirements for strong authorization rates — name, billing info, email, phone, and so on — still apply
eCommerce transactions aren't retried automatically on Recurly. Build your checkout so a customer can resubmit if they mistype their information
Keep PCI scope minimal where possible by using Recurly.js rather than handling card data on your server
Pass the full billing address and CVV wherever your acquirer or card scheme requires it — incomplete data lowers authorization rates
Confirm your address and CVV rejection rules are properly configured in Payment Settings
On Adyen, or when using Kount, set up a custom fraud rule to route these transactions to stricter checks and avoid common eCommerce fraud pitfalls. See Kount and contact [email protected] about Adyen's Revenue Protect custom risk profiles

Error handling and troubleshooting

If a payment method doesn't support one time e-commerce processing, or if your use case doesn't allow non-storage, you will recieve the following error:

Subscription Endpoint or attempting to set false on a purchase payload that contains a plan code.

{
    "error": {
        "type": "validation",
        "message": "Billing info: Store billing info subscriptions require billing info to be stored.",
        "params": [
            {
                "param": "billing_info.store_billing_info",
                "message": "Subscriptions require Billing Info to be stored."
            }
        ]
    }
}

Unsupported Response:

{
    "error": {
        "type": "validation",
        "message": "Billing info: Store billing info unstored billing infos are not supported for this payment gateway.",
        "params": [
            {
                "param": "billing_info.store_billing_info",
                "message": "Unstored Billing Infos are not supported for this payment gateway."
            }
        ]
    }
}

Feature not enabled on site:

Ask support to enable the feature if you see this error.

{
    "error": {
        "type": "validation",
        "message": "The store_billing_info attribute is not enabled for this site.",
        "params": [
            {
                "param": "store_billing_info",
                "message": "The store_billing_info attribute is not enabled for this site."
            }
        ]
    }
}

Webhooks

There are no specific webhook configuration steps for this use case. Please see standard webhook configuration, testing, and best practices in our dedicated guide.
Standard payment or authorized payment webhooks apply to these transactions.

Testing your integration

Depending on your payment method and gateway, refer to that gateway's integration setup, testing guides on Recurly docs, or specific testing guides for payment methods for further instructions.

What's next

Now that you can create new one time ecommerce payments, explore additional use cases on Recurly by visiting our API reference.