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.
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);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.
| Event | What your app does |
|---|---|
checkout.session.completed | Link client_reference_id (your user) to customer and subscription, and turn access on. |
subscription.updated | A renewal, a plan change, or a cancellation scheduled for the end of the period. |
subscription.past_due | A renewal failed and Cycle is retrying: for example, ask the customer to update their card. |
subscription.recovered | A retry worked: clear the notice. |
subscription.canceled | The 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
- Finish setup in the dashboard: your business details, your bank's logins and the card for Cycle's fee. Then press Go live.
- Create a live secret key and a live webhook endpoint, and put them in your production environment.
- 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.