Quickstart

You'll have a working payment flow in about five minutes. By the end of this page you'll have:

Signed up for a Plugipay workspace.
Generated an API key.
Created a checkout session and taken a test payment.

If you'd rather read about concepts first, jump to Concepts. If you'd rather install the CLI or SDK first, see Installation.

Prerequisites

You'll need:

A working email address — we use Huudis SSO for sign-in, and verifying an email is part of sign-up.
About five minutes.
Either a terminal with curl (to follow this page's examples literally) or an SDK installed (covered in Installation).

You do not need to connect a real payment provider for this Quickstart. We'll use the test environment, which simulates payment flows without moving real money.

Head to plugipay.com and click Get started. We use Huudis as our identity provider — you'll create one Huudis account and use it across every Forjio product (Plugipay, Storlaunch, Fulkruma, LinkSnap, and the rest).

Sign-up takes two clicks:

Enter your email and choose a password.
Click the verification link we send you.

If you'd rather sign up with Google or Apple, those buttons appear on the sign-up screen too — they're only shown when the corresponding provider is configured on the Huudis instance. See Social providers for details.

Once you're verified, you land in your first workspace's dashboard.

Workspaces are how Plugipay isolates data. You get one workspace by default, and you can create more for different products or environments. Each workspace has its own customers, payments, API keys, and webhooks.

2. Get an API key

In the dashboard, navigate to Settings → API keys (or go directly to /dashboard/api-keys).

Click Create API key. Give it a name (something like "Quickstart") and an environment:

Test — payments are simulated. No real money moves. Recommended for development.
Live — real payments. Don't use this key from your laptop.

Plugipay shows the secret key once. Copy it into your terminal as an environment variable:

export PLUGIPAY_KEY_ID=pk_test_xxxxxxxxxx
export PLUGIPAY_KEY_SECRET=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Treat the secret like a password. Anyone with PLUGIPAY_KEY_SECRET can charge customers and pull data on the workspace. We never display it again after creation. If you lose it, rotate the key from the portal.

3. Take a test payment

The simplest end-to-end flow is a checkout session: Plugipay generates a hosted payment page, the customer pays on it, and we deliver a webhook when the payment completes.

Create a checkout session with curl:

curl -X POST https://api.plugipay.com/v1/checkout-sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Plugipay-HMAC-SHA256 keyId=$PLUGIPAY_KEY_ID, scope=*, signature=<see below>" \
  -H "X-Plugipay-Timestamp: $(date +%s)" \
  -d '{
    "amount": 50000,
    "currency": "IDR",
    "methods": ["card"],
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel"
  }'

Plugipay uses HMAC signing — you compute a SHA-256 HMAC of timestamp + method + path + body_hash with your secret key. The exact algorithm is documented in API Authentication. The SDKs and CLI handle this for you automatically — you only need to compute it manually with raw curl.

Easier: use the SDK

If you've installed an SDK, the same call becomes:

Node.js:

import { PlugipayClient } from '@forjio/plugipay-node';

const plugipay = new PlugipayClient({
  keyId: process.env.PLUGIPAY_KEY_ID,
  keySecret: process.env.PLUGIPAY_KEY_SECRET,
});

const session = await plugipay.checkoutSessions.create({
  amount: 50000,
  currency: 'IDR',
  description: 'Quickstart test payment',
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
});

console.log('Pay at:', session.url);

Python:

from plugipay import PlugipayClient

plugipay = PlugipayClient(
    key_id=os.environ["PLUGIPAY_KEY_ID"],
    key_secret=os.environ["PLUGIPAY_KEY_SECRET"],
)

session = plugipay.checkout_sessions.create(
    amount=50000,
    currency="IDR",
    description="Quickstart test payment",
    success_url="https://example.com/success",
    cancel_url="https://example.com/cancel",
)

print("Pay at:", session["url"])

Go:

import plugipay "github.com/hachimi-cat/saas-plugipay/sdk/go"

client, _ := plugipay.NewClient(plugipay.ClientOptions{
    KeyID:     os.Getenv("PLUGIPAY_KEY_ID"),
    KeySecret: os.Getenv("PLUGIPAY_KEY_SECRET"),
})

session, _ := client.CheckoutSessions.Create(ctx, plugipay.CheckoutSessionInput{
    Amount:      50000,
    Currency:    "IDR",
    Description: "Quickstart test payment",
    SuccessURL:  "https://example.com/success",
    CancelURL:   "https://example.com/cancel",
})

fmt.Println("Pay at:", session.URL)

Or with the CLI:

plugipay checkout create \
  --amount 50000 \
  --currency IDR \
  --description "Quickstart test payment" \
  --success-url https://example.com/success \
  --cancel-url https://example.com/cancel

Complete the payment

Either way you create the session, the response contains a url field. Open it in your browser. You'll see Plugipay's hosted checkout page.

Because you're in test mode, you can use one of these test cards:

Card number	Result
`4242 4242 4242 4242`	Success
`4000 0000 0000 0002`	Generic decline
`4000 0000 0000 9995`	Insufficient funds
`4000 0027 6000 3184`	3D Secure authentication required

Any future expiry (e.g. 12/30) and any three-digit CVC (e.g. 123) will work.

Submit the form. You'll be redirected to your successUrl with ?session_id= appended.

4. Verify it worked

Check the dashboard at Dashboard → Payments. You should see your test payment listed with the status Succeeded.

Or fetch it via API:

plugipay payments list --limit 1

You did it — you've taken your first Plugipay payment. 🎉

What's next

Your first payment (tutorial) — a deeper version of this Quickstart with refunds, webhooks, and customer attachment.
Installation — install the SDK or CLI properly for your project.
Concepts — understand the model behind customers, sessions, and payments before going further.
API reference — every endpoint, every parameter.