SANDBOX MODE SANDBOX — test mode, no real charges
Payeny
OpenAPI JSON
SDKs & Integration Wrappers

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.

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.