Payeny SDKs & Client Libraries
Integrate your web or SaaS application with Payeny using our official zero-dependency single-file PHP and JavaScript/Node.js SDKs (direct download — no Composer or npm registry package required) or standard REST calls against https://payeny.com/api/v1.
1. PHP Server SDK (PHP 8.1+)
Direct-download single-file PHP SDK (https://payeny.com/sdk/php/PayenyClient.php, ZIP package at /sdk/php, and /sdk/php/README.md — no Composer package required). Covers customers, payments, refunds, subscriptions (including cancel, resume, and changePlan), checkout_sessions, invoices, webhook_endpoints, and verifyWebhookSignature:
<?php
// Direct download: curl -fsSL https://payeny.com/sdk/php/PayenyClient.php -o PayenyClient.php
require_once __DIR__ . '/PayenyClient.php';
use Payeny\PayenyClient;
$payeny = new PayenyClient(getenv('PAYENY_SECRET_KEY'));
// 1. Customers
$customer = $payeny->customers->create([
'name' => 'Alex Rivera',
'email' => 'alex@example.com',
]);
// 2. Payments & Refunds
$payment = $payeny->payments->create([
'amount_cents' => 1000,
'currency' => 'usd',
'payment_method' => 'pm_card_visa',
'customer_id' => $customer['data']['id'],
]);
$refund = $payeny->refunds->create([
'payment_id' => $payment['data']['id'],
'amount_cents' => 1000,
]);
// 3. Subscriptions, Plan Change, Cancel & Resume
$sub = $payeny->subscriptions->create([
'customer_id' => $customer['data']['id'],
'price_id' => 'pri_pro_monthly',
]);
$upgraded = $payeny->subscriptions->changePlan($sub['data']['id'], [
'price_id' => 'pri_business_monthly',
'proration_behavior' => 'create_prorations',
]);
$canceled = $payeny->subscriptions->cancel($sub['data']['id'], [
'cancel_at_period_end' => true,
]);
$resumed = $payeny->subscriptions->resume($sub['data']['id']);
// 4. Checkout Sessions, Invoices & Webhook Endpoints
$session = $payeny->checkoutSessions->create([
'mode' => 'payment',
'amount_cents' => 2500,
'currency' => 'usd',
'success_url' => 'https://example.com/billing/success',
'cancel_url' => 'https://example.com/billing/cancel',
]);
$invoices = $payeny->invoices->list(['customer_id' => $customer['data']['id']]);
$endpoint = $payeny->webhookEndpoints->create([
'url' => 'https://example.com/webhooks/payeny',
'enabled_events' => ['payment.succeeded', 'subscription.canceled'],
]);
// 5. Webhook Signature Verification
$rawBody = file_get_contents('php://input');
$sigHdr = $_SERVER['HTTP_PAYENY_SIGNATURE'] ?? '';
$isValid = PayenyClient::verifyWebhookSignature($rawBody, $sigHdr, $endpoint['data']['secret']);
2. JavaScript / Node.js Client (Node 18+)
Direct-download single-file JavaScript / Node.js SDK (https://payeny.com/sdk/js/payeny.js — no npm package required). Covers customers, payments, refunds, subscriptions (including cancel, resume, and changePlan / change_plan), checkoutSessions, invoices, webhookEndpoints, and webhooks.verifySignature:
// Direct download: curl -fsSL https://payeny.com/sdk/js/payeny.js -o payeny.js
const { PayenyClient } = require('./payeny.js');
const payeny = new PayenyClient(process.env.PAYENY_SECRET_KEY);
// 1. Customers, Payments & Refunds
const customer = await payeny.customers.create({ name: 'Alex Rivera', email: 'alex@example.com' });
const payment = await payeny.payments.create({
amount_cents: 1000,
currency: 'usd',
payment_method: 'pm_card_visa',
customer_id: customer.data.id
});
const refund = await payeny.refunds.create({ payment_id: payment.data.id, amount_cents: 1000 });
// 2. Subscriptions, Plan Change, Cancel & Resume
const sub = await payeny.subscriptions.create({ customer_id: customer.data.id, price_id: 'pri_pro_monthly' });
await payeny.subscriptions.changePlan(sub.data.id, { price_id: 'pri_business_monthly', proration_behavior: 'create_prorations' });
await payeny.subscriptions.cancel(sub.data.id, { cancel_at_period_end: true });
await payeny.subscriptions.resume(sub.data.id);
// 3. Checkout Sessions, Invoices, Webhook Endpoints & Signature Verify
const session = await payeny.checkoutSessions.create({
mode: 'payment',
amount_cents: 2500,
currency: 'usd',
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel'
});
const invoices = await payeny.invoices.list({ customer_id: customer.data.id });
const webhook = await payeny.webhookEndpoints.create({
url: 'https://example.com/webhooks/payeny',
enabled_events: ['payment.succeeded']
});
const verified = payeny.webhooks.verifySignature(rawBody, req.headers['payeny-signature'], webhook.data.secret);
3. Hosted Checkout & Billing Portal Redirects
Payeny hosts both the PCI-isolated Stripe Elements checkout experience and the self-service customer billing portal directly on payeny.com so merchant applications never handle raw card numbers:
| Hosted Surface | URL Pattern | Created Via | Features |
|---|---|---|---|
| Hosted Checkout | https://payeny.com/pay/{cs_id} |
POST /api/v1/checkout_sessions |
Merchant name & plan summary, Stripe Elements under merchant's test keys, inline card/3DS errors, expired/paid session guard, redirects to allowlisted success_url or cancel_url. |
| Billing Portal | https://payeny.com/portal/{session} |
POST /api/v1/billing_portal_sessions |
Current plan, next bill date & amount, change plan with proration preview, cancel at period end, resume subscription, update payment method, invoice history with PDF download, and return link to return_url. |
4. Official Stripe Test Cards (Sandbox Mode)
Use these test card numbers on https://payeny.com/pay/{cs_id} and https://payeny.com/portal/{session} with any future expiration date (e.g. 12/34) and any 3-digit CVC:
| Card Number | Scenario | Expected Sandbox Outcome |
|---|---|---|
4242 4242 4242 4242 |
Success | Payment or subscription succeeds immediately; emits checkout.completed and invoice.paid. |
4000 0000 0000 0341 |
Attaches, fails on charge | PaymentMethod attaches to customer profile, but subsequent charge attempt fails with decline error. |
4000 0025 0000 3155 |
Requires 3DS | Triggers 3D Secure authentication challenge modal before payment confirmation. |
4000 0000 0000 9995 |
Insufficient funds | Charge is declined immediately with inline insufficient_funds error message. |