Skip to content
Paylera

Quickstart

This walks you from a fresh sandbox tenant to an active subscription with your first paid invoice, using nothing but curl.

1. Get a sandbox API key

Sign in to the Paylera Dashboard, open Developers → API tokens, and click Create token. Pick the Sandbox environment, scope it to * for now, and copy the secret.

Terminal window
export PAYLERA_KEY="sk_sandbox_…"
export PAYLERA_BASE="https://api.sandbox.paylera.io"

2. Create a product and a plan

A product describes what you sell; a plan prices it.

Terminal window
curl -X POST "$PAYLERA_BASE/v1/products" \
  -H "Authorization: Bearer $PAYLERA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "starter",
    "name": "Starter",
    "description": "For small teams getting started."
  }'
Terminal window
curl -X POST "$PAYLERA_BASE/v1/plans" \
  -H "Authorization: Bearer $PAYLERA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "product_code": "starter",
    "code": "starter-monthly",
    "currency": "USD",
    "interval": "month",
    "components": [
      { "code": "base", "pricing": { "model": "flat", "amount": "29.00" } }
    ]
  }'

3. Create a customer

Terminal window
curl -X POST "$PAYLERA_BASE/v1/customers" \
  -H "Authorization: Bearer $PAYLERA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "billing_address": { "country": "US", "postal_code": "94105" }
  }'

The response includes a customer_id — keep it.

4. Attach a test payment method

In sandbox, you can attach a tokenised test card directly:

Terminal window
curl -X POST "$PAYLERA_BASE/v1/customers/$CUSTOMER_ID/payment-methods" \
  -H "Authorization: Bearer $PAYLERA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "card", "token": "tok_visa_success" }'

Other useful test tokens: tok_visa_3ds, tok_visa_decline, tok_visa_chargeback. The full list lives in Sandbox & live mode.

5. Subscribe the customer

Terminal window
curl -X POST "$PAYLERA_BASE/v1/subscriptions" \
  -H "Authorization: Bearer $PAYLERA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "plan_code": "starter-monthly",
    "default_payment_method_id": "'"$PAYMENT_METHOD_ID"'"
  }'

Within seconds, the subscription transitions to active, the first invoice is finalised, and the payment is captured. Check the result:

Terminal window
curl "$PAYLERA_BASE/v1/subscriptions/$SUBSCRIPTION_ID" \
  -H "Authorization: Bearer $PAYLERA_KEY"

6. Listen for the events

Add a webhook endpoint pointing at your service:

Terminal window
curl -X POST "$PAYLERA_BASE/v1/admin/webhook-endpoints" \
  -H "Authorization: Bearer $PAYLERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example/webhooks/paylera",
    "events": ["subscription.activated", "invoice.finalized", "payment.succeeded"]
  }'

The response includes the signing secret — store it; it is only returned once. See Verifying signatures for how to use it.

What you just did

In six requests you stood up a billing system that emits events, sends an invoice, captures a payment, and recognises revenue. From here: