Skip to content
On this page

Start here

Your first subscription

Take your first subscription payment in test mode: create a plan, send a customer to checkout, turn their access on from a webhook and let them manage their subscription.

Before you start

  • A free Cycle account. Every business starts in test mode: nothing is charged and no bank contract is needed.
  • An app with a server. Your secret key is used only on the server, never in the browser.
Rather ask your AI?
An AI coding assistant can do every step below for you. See Build with AI.

1. Get a test secret key

In the dashboard, open Developers → Keys & webhooks, create a secret key with the write scope and copy it (it is shown once). Keep it in your server's environment, for example CYCLE_SECRET_KEY=sk_test_…, in a file git ignores.

2. Create a plan

Create a product with its first price. Amounts are in minor units: 1290000 with AMD is ֏ 12 900 a month. Keep the price ID it returns (price_…) in your configuration.

cURL

curl -X POST https://cycle.am/api/v1/products \
  -H "Authorization: Bearer $CYCLE_SECRET_KEY" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Pro", "amount": 1290000, "currency": "AMD", "interval": "month"}'

Add more prices to the same product, a yearly one for example, with POST /api/v1/prices. See Create a price.

3. Add a Subscribe button

When a signed-in user clicks Subscribe, your server opens a checkout session and redirects them to its url: their bank's secure page, where they type their card. Put your own user ID in client_reference_id; it comes back when they have paid.

// POST /billing/subscribe
const response = await fetch('https://cycle.am/api/v1/checkout/sessions', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.CYCLE_SECRET_KEY}`,
        Accept: 'application/json',
        'Content-Type': 'application/json',
        'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify({
        price: process.env.CYCLE_PRICE_PRO,
        customer_email: user.email,
        client_reference_id: String(user.id),
        success_url: 'https://your-app.example/billing/success?session={CHECKOUT_SESSION_ID}',
    }),
});

const { data: session } = await response.json();
res.redirect(303, session.url);
Never build a card form in your app. Customers always type their card on the bank's page.

4. Pay with a test card

In test mode the bank page is Cycle's simulated bank. Pay with 4242 4242 4242 4242, any future expiry date and any CVC. The customer lands on your success_url. There, GET /api/v1/checkout/sessions/{id} returns status: completed once it's paid (an open session is checked with the bank first). Test cards lists cards that decline, ask for 3-D Secure or fail on renewal.

5. Turn access on with webhooks

Let events decide access, not the success page: the customer may close the tab, and renewals happen with nobody present. Add an endpoint (a public https:// URL) under Developers → Keys & webhooks, or with Create a webhook endpoint, and keep its signing secret as CYCLE_WEBHOOK_SECRET.

EventWhat your app does
checkout.session.completedLink client_reference_id (your user) to customer and subscription, and turn access on.
subscription.updatedA renewal, a plan change, or a cancellation scheduled for the end of the period.
subscription.past_dueA renewal failed and Cycle is retrying: for example, ask the customer to update their card.
subscription.recoveredA retry worked: clear the notice.
subscription.canceledThe subscription ended: turn access off.

Node.js (Express)

app.post('/webhooks/cycle', express.raw({ type: 'application/json' }), async (req, res) => {
    if (!verifyCycleSignature(req.body.toString(), req.get('Cycle-Signature') ?? '', process.env.CYCLE_WEBHOOK_SECRET)) {
        return res.sendStatus(400);
    }

    const event = JSON.parse(req.body);

    if (await alreadyProcessed(event.id)) {
        return res.sendStatus(200);
    }

    if (event.type === 'checkout.session.completed') {
        const session = event.data.object;
        await grantAccess(session.client_reference_id, session.customer, session.subscription);
    } else if (event.type === 'subscription.canceled') {
        await revokeAccess(event.data.object.customer);
    }

    res.sendStatus(200);
});

verifyCycleSignature is in Verify the signature, with a PHP version. Answer within 10 seconds and do slow work in a background job.

6. Let customers manage their subscription

For a "Manage subscription" button, ask for a portal link and redirect to it. In the customer portal they change their card, switch plan or cancel, as you allow under Settings → Customer portal. The link works for an hour, so make a new one each time.

cURL

curl -X POST https://cycle.am/api/v1/customers/cus_8f2a1c/portal-links \
  -H "Authorization: Bearer $CYCLE_SECRET_KEY" -H "Accept: application/json"

7. Go live

  1. Finish setup in the dashboard: your business details, your bank's logins and the card for Cycle's fee. Then press Go live.
  2. Create a live secret key and a live webhook endpoint, and put them in your production environment.
  3. Create your live products and prices (test and live data never mix) and use their IDs in production.

Your code stays the same: only the keys and IDs change.