Using a token

Use the Recurly token you generated with Recurly.js to create purchases, subscriptions, or update billing info via API v3—examples in every official client library plus key rules on token lifespan and security.

Once Recurly.js encrypts card data and returns a token (token_id), your server can pass that token to Recurly’s API in place of raw payment details. This page shows:

  • Code samples (Ruby, Node, Python, Java, C#) for creating a purchase with a token
  • Which API endpoints accept token_id
  • Lifespan, reuse rules, and security best-practices

Tokens keep you out of PCI scope, but they expire 20 minutes after creation—so move them from browser → backend → Recurly quickly.

Take into account:

  • Faster PCI compliance: SAQ-A level—no sensitive data touches your servers.
  • Consistent across endpoints: The same token_id works for purchases, subscriptions, or standalone billing-info updates.
  • Safe to retry: Tokens can be reused within 20 minutes, simplifying idempotent flows and error recovery.

Using a token to create a purchase

purchase = {
  currency: "USD",
  account: {
    code: account_code,
    billing_info: { token_id: rjs_token_id }
  },
  subscriptions: [{ plan_code: plan_code }]
}
invoice_collection = @client.create_purchase(body: purchase)
const purchaseReq = {
  currency: 'USD',
  account: {
    code: accountCode,
    billingInfo: { tokenId: rjsTokenId }
  },
  subscriptions: [{ planCode }]
};
const invoiceCollection = await client.createPurchase(purchaseReq);
purchase = {
    "currency": "USD",
    "account": {
        "code": account_code,
        "billing_info": {"token_id": rjs_token_id},
    },
    "subscriptions": [{"plan_code": plan_code}],
}
invoice_collection = client.create_purchase(purchase)
PurchaseCreate purchase = new PurchaseCreate()
  .currency("USD")
  .account(new AccountPurchase()
      .code(accountCode)
      .billingInfo(new BillingInfoCreate().tokenId(rjsTokenId)))
  .subscriptions(List.of(new SubscriptionPurchase().planCode(planCode)));

InvoiceCollection collection = client.createPurchase(purchase);
var purchaseReq = new PurchaseCreate {
  Currency = "USD",
  Account = new AccountPurchase {
    Code = accountCode,
    BillingInfo = new BillingInfoCreate { TokenId = rjsTokenId }
  },
  Subscriptions = new List<SubscriptionPurchase> {
    new SubscriptionPurchase { PlanCode = planCode }
  }
};
InvoiceCollection collection = client.CreatePurchase(purchaseReq);

Token rules and security

RuleDetail
LifespanValid for 20 minutes from creation.
ReuseCan be used multiple times during that window (e.g., account + subscription + one-time charge).
StorageToken lives only in the Recurly vault; if it expires it cannot be recovered.
TransportSend to your server over HTTPS only—treat it like any auth credential.

Tip: If you receive transaction_error.code = invalid_token, request a fresh token from Recurly.js and retry.


Endpoints that accept token_id

Attach the token like so:

"billing_info": {
  "token_id": "1d1e4f0447c2b7e6d2f6cbf5c4b2c9aa"
}

That’s it—Recurly swaps the token for the underlying card or bank details and completes the request while you stay out of PCI scope.