SANDBOX MODE SANDBOX — test mode, no real charges
Payeny
Payeny Sandbox Infrastructure — v1

Payeny Developer Documentation

Payeny provides unified payment, hosted checkout, recurring subscription, billing portal, and webhook infrastructure for SaaS and commerce applications with a flat platform fee of $0.25 per transaction. Everything in the developer sandbox operates in Stripe TEST mode only (PAYENY_MODE=sandbox) with isolated per-merchant credentials and zero live charges.

Quickstart: Integrate Your Application

Follow these four steps to create a product and price, register a customer, redirect to Payeny's hosted checkout page (https://payeny.com/pay/{cs_id}), and verify the signed outbound webhook:

# 1. Verify Sandbox Health
curl -X GET https://payeny.com/api/v1/health

# 2. Create a Product & Recurring Monthly Price ($29.00 USD)
curl -X POST https://payeny.com/api/v1/products \
  -H "Authorization: Bearer sec_test_acme_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: idem_acme_prod_01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Studio Pro",
    "description": "Studio Pro Subscription"
  }'

curl -X POST https://payeny.com/api/v1/prices \
  -H "Authorization: Bearer sec_test_acme_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: idem_acme_price_01" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_8a7b6c5d4e3f2a1b0c9d8e7f",
    "type": "recurring",
    "interval": "month",
    "currency": "usd",
    "unit_amount": 2900
  }'

# 3. Create a Customer mapped to your application user ID
curl -X POST https://payeny.com/api/v1/customers \
  -H "Authorization: Bearer sec_test_acme_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: idem_acme_cus_42" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@example.com",
    "name": "Alex Rivera",
    "external_id": "usr_42"
  }'

# 4. Create a Hosted Checkout Session & Redirect User to data.url
curl -X POST https://payeny.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer sec_test_acme_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: idem_acme_cs_1001" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "subscription",
    "price_id": "price_1a2b3c4d5e6f7a8b9c0d1e2f",
    "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
    "client_reference_id": "usr_42",
    "success_url": "https://example.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://example.com/billing/cancel"
  }'

Authentication (Bearer sec_test_...)

Authenticate every `/api/v1` call by passing your merchant tenant's secret key in the Authorization HTTP header:

Authorization: Bearer sec_test_acme_9f8e7d6c5b4a3210fedcba9876543210
  • Per-Merchant Key Isolation: Each merchant tenant is issued a publishable key (pub_test_...) and a secret key (sec_test_...). Secret keys are hashed with SHA-256 + a server-side pepper from secrets/payeny.env and displayed once at creation.
  • Tenant Resolution: Payeny resolves the calling merchant from the Bearer token and loads that merchant's Stripe test credentials from secrets/stripe_<slug>.env with no fallback to any other merchant's keys.
  • Sandbox Enforcement: Any sec_live_... key is rejected with HTTP 401 while in sandbox mode. If PAYENY_MODE=sandbox and any loaded Stripe key does not start with pk_test_ or sk_test_, payment routes refuse to boot and return HTTP 503 (code: "non_test_key_in_sandbox").

Errors & Idempotency (Idempotency-Key)

All successful responses return {"data": {...}, "request_id": "req_...", "livemode": false}. All errors return:

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "route_not_found",
    "message": "The requested endpoint was not found."
  },
  "request_id": "req_1234567890ab",
  "livemode": false
}
HTTP Status Error Type Meaning
400bad_requestInvalid JSON or missing required field.
401unauthorizedMissing, invalid, revoked, or sec_live_ Bearer key in sandbox.
404not_foundResource or endpoint not found for the authenticated merchant.
409idempotency_conflictSame Idempotency-Key sent with a different request body within 24 hours.
422validation_errorDomain allowlist validation failure (e.g., non-HTTPS or unapproved redirect URL) or invalid enum parameter.
503configuration_errornon_test_key_in_sandbox — Sandbox guard blocked non-test Stripe credentials.

Idempotency Behavior: Pass Idempotency-Key: <unique-key> on any POST request. Payeny stores key + merchant + request_hash + response for 24 hours and forwards the key to Stripe. Replaying the same key with the same body replays the stored response; replaying the same key with a different body returns 409 idempotency_conflict.

System & Health

GET /api/v1/health

Health Check

Check API and platform operational status.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/health \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Platform operational

Payments & Charges

GET /api/v1/payments

List Payments

List all charges and payments for the authenticated merchant.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/payments \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of payments
400
401
404
429
POST /api/v1/payments

Create Payment

Create a direct charge or authorization.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
amount_centsintegeryes
currencystringno
customer_idstringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/payments \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_ffes3qxy" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 2900,
  "currency": "usd",
  "customer_id": "cus_3a1b2c3d4e5f"
}'
Responses & Error Codes
StatusDescription
201Payment created
400
401
409
422
429
GET /api/v1/payments/{id}

Retrieve Payment

Retrieve details for a specific payment, including checkout_session_id link.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/payments/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Payment object
400
401
404
429

Checkout Sessions

GET /api/v1/payment_methods

List Payment Methods

Lists supported and attached payment methods for the merchant or a specific customer.

Parameters
NameInTypeRequiredDescription
customer_idquerystringnoOptional customer ID to list attached methods for.
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/payment_methods   -H "Authorization: Bearer sec_test_sample_key"
Response (200 OK)
{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "pm_card_visa",
        "object": "payment_method",
        "type": "card",
        "card": {
          "brand": "visa",
          "last4": "4242",
          "exp_month": 12,
          "exp_year": 2028
        },
        "livemode": false
      }
    ]
  },
  "request_id": "req_sample_pms",
  "livemode": false
}
Responses & Error Codes
StatusDescription
200List of payment methods
401Missing or invalid secret key
GET /api/v1/checkout_sessions

List Checkout Sessions

Retrieve a list of checkout sessions for the authenticated merchant.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of checkout sessions
400
401
404
429
POST /api/v1/checkout_sessions

Create Checkout Session

Create a checkout session for one-time payment (mode=payment, amount_cents) or subscription (mode=subscription, price_id).

Request Body (Request JSON payload)
FieldTypeRequiredDescription
modestringnopayment (default) or subscription
amount_centsintegernoRequired for mode=payment if no price_id
currencystringnoThree-letter ISO currency code (e.g. usd)
success_urlstringyesRequired. HTTPS URL on an allowlisted merchant domain to redirect the customer after payment succeeds (returns 422 invalid_request_error with param="success_url" when absent or empty).
cancel_urlstringyesRequired. HTTPS URL on an allowlisted merchant domain to redirect the customer if checkout is canceled (returns 422 invalid_request_error with param="cancel_url" when absent or empty).
client_reference_idstringnoOptional merchant order or reference ID
customer_emailstringnoOptional customer email address
line_itemsarraynoOptional array of line items
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_fxgpn97n" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "payment",
  "amount_cents": 4900,
  "currency": "usd",
  "success_url": "https://example.com/checkout/success",
  "cancel_url": "https://example.com/checkout/cancel",
  "client_reference_id": "ord_ref_123",
  "customer_email": "buyer@example.com",
  "line_items": []
}'
Responses & Error Codes
StatusDescription
201Checkout session created
400
401
409
422
429
GET /api/v1/checkout_sessions/{id}

Retrieve Checkout Session

Retrieve details for a specific checkout session.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/checkout_sessions/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Session details
400
401
404
429

Subscriptions & Recurring

GET /api/v1/subscriptions

List Subscriptions

List active and historical subscriptions.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/subscriptions \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of subscriptions
400
401
404
429
POST /api/v1/subscriptions

Create Subscription

Create a recurring billing subscription.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
customer_idstringyesCustomer ID (cus_...)
price_idstringyesRecurring catalog price ID (price_...)
payment_methodstringnoOptional Stripe payment method ID or test token (e.g., pm_card_visa).
trial_period_daysintegernoOptional trial duration in days (0 to 730).
couponstringnoOptional coupon ID or promotion code (e.g., ELEPT20OFF). Returns HTTP 400 invalid_coupon if invalid.
use_test_clockbooleannoTest-mode only: when true, provisions a Stripe Test Clock for deterministic time advancement via POST /subscriptions/{id}/advance_clock. Refused in live mode (403 test_mode_only).
test_clock / clockstring | booleannoTest-mode only: optional Stripe Test Clock ID (clock_...) or boolean flag to attach to the customer and subscription.
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/subscriptions \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_itqioh5x" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_3a1b2c3d4e5f",
  "price_id": "pri_pro_monthly"
}'
Responses & Error Codes
StatusDescription
201Subscription created
400
401
409
422
429
GET /api/v1/subscriptions/{id}

Retrieve Subscription

Retrieve subscription status.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/subscriptions/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Subscription details
400
401
404
429
POST /api/v1/subscriptions/{id}/change_plan

Change subscription plan/price

Updates an active subscription to a new recurring price.

Parameters
NameInTypeRequiredDescription
idpathstringyesSubscription ID (sub_...)
Request Body (Request JSON payload)
FieldTypeRequiredDescription
price_idstringyes
proration_behaviorstringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/subscriptions/sample_id/change_plan \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_vlern6f1" \
  -H "Content-Type: application/json" \
  -d '{
  "price_id": "price_abc123",
  "proration_behavior": "sample_proration_behavior"
}'
Responses & Error Codes
StatusDescription
200Subscription plan updated
400
401
404Subscription or price not found
409
422
429
POST /api/v1/subscriptions/{id}/cancel

Cancel a subscription

Cancels an active subscription immediately or at the current billing period end.

Parameters
NameInTypeRequiredDescription
idpathstringyesSubscription ID (sub_...)
Request Body (Request JSON payload)
FieldTypeRequiredDescription
cancel_at_period_endbooleanno
immediatebooleanno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/subscriptions/sample_id/cancel \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_r1w9yw2d" \
  -H "Content-Type: application/json" \
  -d '{
  "cancel_at_period_end": false,
  "immediate": true
}'
Responses & Error Codes
StatusDescription
200Subscription canceled
400
401
404Subscription not found
409
422
429
DELETE /api/v1/subscriptions/{id}

Cancel a subscription (DELETE)

Cancels an active subscription immediately via HTTP DELETE (equivalent to POST /subscriptions/{id}/cancel).

Parameters
NameInTypeRequiredDescription
idpathstringyesSubscription ID (sub_...)
Executable Sandbox Samples
curl -X DELETE https://payeny.com/api/v1/subscriptions/sub_sample_123   -H "Authorization: Bearer sec_test_sample_key"
Response (200 OK)
{
  "data": {
    "id": "sub_sample_123",
    "status": "canceled",
    "customer_id": "cus_sample_456",
    "canceled_at": 1792744720,
    "livemode": false
  },
  "request_id": "req_sample_del",
  "livemode": false
}
Responses & Error Codes
StatusDescription
200Subscription canceled
400Invalid cancellation parameters
401Missing or invalid secret key
404Subscription not found
POST /api/v1/subscriptions/{id}/resume

Resume a subscription

Resumes a subscription scheduled for cancellation at period end.

Parameters
NameInTypeRequiredDescription
idpathstringyesSubscription ID (sub_...)
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/subscriptions/sample_id/resume \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_j8z98iof" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Responses & Error Codes
StatusDescription
200Subscription resumed
400
401
404Subscription not found
409
422
429
POST /api/v1/subscriptions/{id}/payment_method

Update or detach subscription payment method

Attaches a new default payment method to the subscription and customer, or detaches all payment methods when detach: true or payment_method: null is passed.

curl -X POST https://payeny.com/api/v1/subscriptions/sub_sample_123/payment_method \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Content-Type: application/json" \
  -d '{"payment_method": "pm_card_visa"}'
POST /api/v1/subscriptions/{id}/advance_clock Test Mode Only (403 test_mode_only in Live)

Advance subscription test clock (Test Mode Only)

Advances the Stripe Test Clock attached to a sandbox subscription by advance_days or advance_seconds (or to frozen_time) to exercise trial conversion, scheduled period-end downgrades/cancellations, recurring renewals, and past_due dunning retries (days 1, 3, and 7). Strictly test-mode only: returns HTTP 403 with code: "test_mode_only" in live mode.

curl -X POST https://payeny.com/api/v1/subscriptions/sub_sample_123/advance_clock \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Content-Type: application/json" \
  -d '{"advance_days": 31}'
POST /api/v1/coupons

Create, List, Retrieve & Delete Coupons (/api/v1/coupons, /api/v1/coupons/{id})

Manage percentage or fixed-amount discount coupons. Unrecognized or invalid coupon codes return HTTP 400 with code: "invalid_coupon".

curl -X POST https://payeny.com/api/v1/coupons \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Content-Type: application/json" \
  -d '{"id": "ELEPT20OFF", "percent_off": 20, "duration": "once"}'
POST /api/v1/events/{id}/replay Test Mode Only (403 test_mode_only in Live)

Replay webhook event (Test Mode Only)

Replays a stored webhook event in single, duplicate, or out_of_order mode with a fresh HMAC-SHA256 Payeny-Signature. Strictly test-mode only: returns HTTP 403 with code: "test_mode_only" in live mode.

curl -X POST https://payeny.com/api/v1/events/evt_sample_123/replay \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Content-Type: application/json" \
  -d '{"mode": "single"}'
POST /api/v1/billing_portal_sessions

Create customer billing portal session

Generates a secure hosted portal URL where a customer can manage billing and payment methods.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
customer_idstringyes
return_urlstringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/billing_portal_sessions \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_poyisqly" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_0f2d32a8d5c63d658c60",
  "return_url": "https://example.com/account"
}'
Responses & Error Codes
StatusDescription
201Billing portal session created
400
401
409
422
429

Customers

GET /api/v1/customers

List Customers

List all customer accounts.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/customers \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of customers
400
401
404
429
POST /api/v1/customers

Create Customer

Create a new customer profile.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
emailstringyes
namestringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/customers \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_f9jthbyc" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "buyer@example.com",
  "name": "Jane Doe"
}'
Responses & Error Codes
StatusDescription
201Customer created
400
401
409
422
429
GET /api/v1/customers/{id}

Retrieve Customer

Retrieve customer profile.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/customers/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Customer details
400
401
404
429
PATCH /api/v1/customers/{id}

Update a customer

Updates name, email, or metadata on a customer profile.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Request Body (Request JSON payload)
FieldTypeRequiredDescription
namestringno
emailstringno
phonestringno
metadataobjectno
Executable Sandbox Samples
curl -X PATCH https://payeny.com/api/v1/customers/sample_id \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_b8uk1e2m" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "phone": "+15555550199",
  "metadata": "sample_metadata"
}'
Responses & Error Codes
StatusDescription
200Customer updated
400
401
404Customer not found
409
422
429

Products & Prices

GET /api/v1/products

List Products

List all merchant catalog products.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/products \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of products
400
401
404
429
POST /api/v1/products

Create Product

Create a new catalog product.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
namestringyes
descriptionstringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/products \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_ngc7ejvd" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Cloud Storage Sync Plan",
  "description": "Object sync package"
}'
Responses & Error Codes
StatusDescription
201Product created
400
401
409
422
429
GET /api/v1/products/{id}

Retrieve Product

Retrieve product catalog item.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/products/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Product details
400
401
404
429
PATCH /api/v1/products/{id}

Update a product

Updates specific fields on an existing product catalog item.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Request Body (Request JSON payload)
FieldTypeRequiredDescription
namestringno
descriptionstringno
activebooleanno
metadataobjectno
Executable Sandbox Samples
curl -X PATCH https://payeny.com/api/v1/products/sample_id \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_8eauykgf" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Pro Membership",
  "description": "Updated membership details",
  "active": true,
  "metadata": "sample_metadata"
}'
Responses & Error Codes
StatusDescription
200Product updated
400
401
404Product not found
409
422
429
GET /api/v1/prices

List Prices

List all pricing plans.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/prices \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of prices
400
401
404
429
POST /api/v1/prices

Create Price

Create a one-time or recurring price plan.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
product_idstringyes
unit_amountintegeryes
currencystringno
typestringno
intervalstringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/prices \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_6pzqoagv" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "prod_sample_sync",
  "unit_amount": 2900,
  "currency": "usd",
  "type": "recurring",
  "interval": "month"
}'
Responses & Error Codes
StatusDescription
201Price created
400
401
409
422
429
GET /api/v1/prices/{id}

Retrieve Price

Retrieve details for a price.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/prices/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Price details
400
401
404
429
PATCH /api/v1/prices/{id}

Update a price

Updates an existing price record.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Request Body (Request JSON payload)
FieldTypeRequiredDescription
activebooleanno
nicknamestringno
metadataobjectno
Executable Sandbox Samples
curl -X PATCH https://payeny.com/api/v1/prices/sample_id \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_7ver4ept" \
  -H "Content-Type: application/json" \
  -d '{
  "active": true,
  "nickname": "Updated Monthly Pro",
  "metadata": "sample_metadata"
}'
Responses & Error Codes
StatusDescription
200Price updated
400
401
404Price not found
409
422
429

Invoices

GET /api/v1/invoices

List Invoices

List invoices for the authenticated merchant.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/invoices \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of invoices
400
401
404
429
GET /api/v1/invoices/{id}

Retrieve Invoice

Retrieve invoice record.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/invoices/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Invoice details
400
401
404
429
GET /api/v1/invoices/{id}/pdf

Download invoice PDF

Downloads the printable PDF or invoice rendering for a given invoice.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/invoices/sample_id/pdf \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Invoice receipt PDF document
400
401
404Invoice not found
429

Refunds

GET /api/v1/refunds

List Refunds

List refunds issued by the merchant.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/refunds \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of refunds
400
401
404
429
POST /api/v1/refunds

Create Refund

Issue a refund for a previously captured payment.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
payment_idstringyes
amount_centsintegernoOptional partial amount. Full amount refunded if omitted.
reasonstringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/refunds \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_zk2lqc7s" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_id": "pay_356c860bac52fa30ec10",
  "amount_cents": 1000,
  "reason": "requested_by_customer"
}'
Responses & Error Codes
StatusDescription
201Refund created
400
401
409
422
429
GET /api/v1/refunds/{id}

Retrieve Refund

Retrieve details of a refund.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/refunds/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Refund details
400
401
404
429

Events & Webhooks

GET /api/v1/events

List Events

List audit ledger events scoped to the merchant.

Parameters
NameInTypeRequiredDescription
typequerystringnoFilter by event type, e.g. checkout.completed
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/events \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of events
400
401
404
429
GET /api/v1/events/{id}

Retrieve Event

Retrieve an event from the audit ledger.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/events/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Event details
400
401
404
429
POST /api/v1/events/{id}/resend

Resend Event

Redeliver an existing stored event to merchant webhooks using the same event ID.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/events/sample_id/resend \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_55idc71f" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Responses & Error Codes
StatusDescription
200Event redelivered
400
401
404
409
422
429
POST /api/v1/webhook_deliveries/{id}/resend

Resend a Webhook Delivery

Redelivers an existing webhook event delivery to the merchant endpoint without creating duplicate event records.

Parameters
NameInTypeRequiredDescription
idpathstringyesWebhook delivery ID (del_...)
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/webhook_deliveries/del_sample_123/resend   -H "Authorization: Bearer sec_test_sample_key"
Response (200 OK)
{
  "data": {
    "id": "evt_sample_123",
    "delivery_id": "del_sample_456",
    "event": "payment.succeeded",
    "status": "delivered",
    "http_code": 200,
    "redelivered": true,
    "livemode": false
  },
  "request_id": "req_sample_deliv",
  "livemode": false
}
Responses & Error Codes
StatusDescription
200Webhook delivery re-queued
401Missing or invalid secret key
GET /api/v1/webhook_endpoints

List Webhook Endpoints

List registered webhook endpoints for the authenticated merchant.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of webhook endpoints
400
401
404
429
POST /api/v1/webhook_endpoints

Create Webhook Endpoint

Register a new webhook URL (must be https). Returns the signing secret (whsec_) once only.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
urlstringyes
descriptionstringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_qx2hlwej" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/payeny",
  "description": "Production Webhook"
}'
Responses & Error Codes
StatusDescription
201Webhook endpoint created
400
401
409
422
429
DELETE /api/v1/webhook_endpoints/{id}

Delete Webhook Endpoint

Remove a registered webhook endpoint.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X DELETE https://payeny.com/api/v1/webhook_endpoints/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Webhook endpoint deleted
400
401
404
429
GET /api/v1/webhook_endpoints/{id}

Retrieve Webhook Endpoint

Retrieve details of a registered webhook endpoint scoped to the merchant.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/webhook_endpoints/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Webhook endpoint details
400
401
404
429

Connect Accounts & Onboarding

GET /api/v1/connect/accounts

List Connect Accounts

List marketplace Connect accounts.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/connect/accounts \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of connect accounts
400
401
404
429
POST /api/v1/connect/accounts

Create Connect Account

Provision a new Connect standard or express account.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
emailstringyes
business_namestringno
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/connect/accounts \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_r6tjl8g5" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "seller@example.com",
  "business_name": "Seller Co"
}'
Responses & Error Codes
StatusDescription
201Connect account created
400
401
409
422
429
GET /api/v1/connect/accounts/{id}

Retrieve Connect Account

Retrieve account details and capability statuses.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/connect/accounts/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Account details
400
401
404
429
POST /api/v1/connect/accounts/{id}/account_links

Create Account Link

Create an onboarding or dashboard account link for a connected seller.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/connect/accounts/sample_id/account_links \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_imnkf4aa" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Responses & Error Codes
StatusDescription
200Account link URL
400
401
404
409
422
429
POST /api/v1/connect/accounts/{id}/onboarding_session

Create Onboarding Session

Create an embedded onboarding session for a connected account.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/connect/accounts/sample_id/onboarding_session \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_snnnpiqe" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Responses & Error Codes
StatusDescription
200Onboarding session token and URL
400
401
404
409
422
429
POST /api/v1/connect/accounts/{id}/verify-sandbox

Verify Sandbox Account (Test Mode Only)

Simulate identity and payouts verification for a test Connect account. [TEST MODE ONLY] Rejects with HTTP 400 not_available_in_livemode if invoked in livemode.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/connect/accounts/sample_id/verify-sandbox \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_5a3sdomg" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Responses & Error Codes
StatusDescription
200Account verified in sandbox
400
401
404
409
422
429

Merchants

GET /api/v1/merchants

List Connected Merchants

List connected merchant accounts accessible to the caller.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/merchants \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of merchants
400
401
404
429
POST /api/v1/merchants

Create Merchant

Register a new connected merchant.

Request Body (Request JSON payload)
FieldTypeRequiredDescription
namestringyes
emailstringyes
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/merchants \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_ci0b4jy1" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Partner Merchant",
  "email": "partner@example.com"
}'
Responses & Error Codes
StatusDescription
201Merchant registered
400
401
409
422
429
GET /api/v1/merchants/{id}

Retrieve Merchant

Retrieve details for a specific merchant.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/merchants/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Merchant details
400
401
404
429

Transactions & Balance

GET /api/v1/transactions

List marketplace transactions

Returns a list of marketplace order and payment transactions.

Parameters
NameInTypeRequiredDescription
limitqueryintegerno
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/transactions \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of transactions
400
401
404
429
GET /api/v1/transactions/{id}

Retrieve a transaction

Retrieves details for a specific marketplace transaction.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/transactions/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Transaction details
400
401
404Transaction not found
429
GET /api/v1/balance

Retrieve merchant balance

Returns available and pending ledger balances for the authenticated merchant.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/balance \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Merchant balance
400
401
404
429

Redirect Domains

GET /api/v1/payouts/{id}/trace

Trace Payout Settlement & Transit

Retrieves real-time settlement and banking transit lifecycle status for a payout or balance sweep.

Parameters
NameInTypeRequiredDescription
idpathstringyesPayout ID (po_...)
Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/payouts/sample_id/trace   -H "Authorization: Bearer sec_test_sample_key"
Response (200 OK)
{
  "data": {
    "payout_id": "po_sample_12345678",
    "status": "paid",
    "amount_cents": 12500,
    "currency": "usd",
    "destination": "ba_stripe_express_connected",
    "estimated_arrival": "2026-10-27",
    "trace_id": "trc_sample_789",
    "livemode": false
  },
  "request_id": "req_sample_trace",
  "livemode": false
}
Responses & Error Codes
StatusDescription
200Payout trace events returned
401Missing or invalid secret key
GET /api/v1/allowed_redirect_domains

List Allowed Redirect Domains

List allowlisted hostnames permitted for checkout success_url and cancel_url.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/allowed_redirect_domains \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200List of allowed domains
400
401
404
429
POST /api/v1/allowed_redirect_domains

Add Allowed Redirect Domain

Allowlist a bare hostname or explicit wildcard subdomain (*.example.com).

Request Body (Request JSON payload)
FieldTypeRequiredDescription
domainstringyes
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/allowed_redirect_domains \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Idempotency-Key: idem_lusbmpjz" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "example.com"
}'
Responses & Error Codes
StatusDescription
201Domain added to allowlist
400
401
409
422
429
DELETE /api/v1/allowed_redirect_domains/{id}

Delete Allowed Redirect Domain

Remove a domain from the allowlist.

Parameters
NameInTypeRequiredDescription
idpathstringyes
Executable Sandbox Samples
curl -X DELETE https://payeny.com/api/v1/allowed_redirect_domains/sample_id \
  -H "Authorization: Bearer sec_test_sample_key"
Responses & Error Codes
StatusDescription
200Domain removed from allowlist
400
401
404
429

Platform & Fee Architecture

GET /api/v1/platform-fee

Get Platform Fee Setting

Retrieve the active master platform fee setting (currently $0.25 per transaction with no percentage surcharge).

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/platform-fee   -H "Authorization: Bearer sec_test_sample_key"
Response (200 OK)
{
  "data": {
    "platform_fee_cents": 25,
    "platform_fee_percent": 0,
    "formatted": "$0.25 per transaction",
    "platform_fee": 25  },
  "request_id": "req_sample_fee",
  "livemode": false
}
Responses & Error Codes
StatusDescription
200Platform fee settings
401Missing or invalid secret key
POST /api/v1/platform-fee

Update Platform Fee Setting

Update the single platform fee setting ($0.25 flat fee single source of truth).

Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/platform-fee   -H "Authorization: Bearer sec_test_sample_key"   -H "Content-Type: application/json"   -d '{
    "platform_fee_cents": 25,
    "platform_fee_percent": 0
  }'
Response (200 OK)
{
  "data": {
    "success": true,
    "platform_fee_cents": 25,
    "platform_fee_percent": 0,
    "formatted": "$0.25 per transaction"
  },
  "request_id": "req_sample_fee_post",
  "livemode": false
}
Responses & Error Codes
StatusDescription
200Platform fee updated
401Missing or invalid secret key
GET /api/v1/disputes

List Disputes

Retrieve a list of payment disputes and chargebacks for the authenticated merchant.

curl -X GET https://payeny.com/api/v1/disputes \
  -H "Authorization: Bearer sec_test_sample_key"
GET /api/v1/disputes/{id}

Retrieve Dispute

Retrieve details of a specific dispute or chargeback by ID.

curl -X GET https://payeny.com/api/v1/disputes/dp_sample_123 \
  -H "Authorization: Bearer sec_test_sample_key"
POST /api/v1/disputes/{id}/evidence

Submit Dispute Evidence

Submit or stage dispute evidence (product description, customer communication, receipt, uncategorized text) for an open dispute/chargeback.

Parameters
NameInTypeRequiredDescription
idpathstringyesDispute identifier (dp_...).
product_descriptionbodystringnoDescription of the product or service provided.
customer_namebodystringnoCustomer full name.
customer_email_addressbodystringnoCustomer email address.
uncategorized_textbodystringnoAdditional supporting text evidence.
submitbodybooleannoWhether to immediately submit the evidence to the card network (default true).
Executable Sandbox Samples
curl -X POST https://payeny.com/api/v1/disputes/dp_sample_123/evidence \
  -H "Authorization: Bearer sec_test_sample_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_description": "Elept Pro Monthly SaaS Subscription",
    "customer_name": "Alex Rivera",
    "uncategorized_text": "Customer actively used the subscription during the billing period.",
    "submit": true
  }'
GET /api/v1/api_keys

List API Keys

List Payeny API key metadata (id, type, mode, prefix, last4, created_at, status) for the authenticated merchant. Never returns raw secret keys or Stripe secret key values.

Executable Sandbox Samples
curl -X GET https://payeny.com/api/v1/api_keys \
  -H "Authorization: Bearer sec_test_sample_key"

Outbound Webhooks & Signature Verification

Open Full Webhooks Page →

Payeny dispatches signed HTTP POST requests for 26 canonical events: checkout.completed, checkout.session.completed, payment.created, payment.succeeded, payment.captured, payment.canceled, payment.failed, refund.created, subscription.created, subscription.updated, subscription.canceled, subscription.renewed, subscription.payment_failed, invoice.created, invoice.paid, invoice.payment_failed, dispute.created, dispute.closed, payout.status, transaction.agreed, merchant.created, merchant.updated, portal.session.created, portal.session.accessed, usage.recorded, and usage.invoiced.

Payload Format: {id: "evt_...", type, created, livemode: false, merchant, data: {object}}
Signature Header: Payeny-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" using the merchant's whsec_ webhook secret>
Retry Policy: Non-2xx responses or timeouts over 10s are retried with exponential backoff at 1m, 5m, 30m, 2h, 12h, and 24h, then marked failed. Every delivery attempt is logged and supports manual resend.

PHP Signature Verification
<?php
$rawBody = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_PAYENY_SIGNATURE'] ?? '';
$secret = getenv('PAYENY_WEBHOOK_SECRET'); // whsec_...

$parts = [];
foreach (explode(',', $sigHeader) as $seg) {
    [$k, $v] = array_pad(explode('=', trim($seg), 2), 2, '');
    $parts[$k] = $v;
}
$expected = hash_hmac('sha256', ($parts['t'] ?? '') . '.' . $rawBody, $secret);
if (!hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(400);
    exit('Invalid signature');
}
$event = json_decode($rawBody, true);
JavaScript / Node.js Signature Verification
import crypto from 'node:crypto';

export function verifyPayenyWebhook(rawBody, sigHeader, secret) {
  const parts = Object.fromEntries(sigHeader.split(',').map(p => p.trim().split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`, 'utf8').digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(parts.v1 || '', 'hex'))) {
    throw new Error('Invalid Payeny-Signature');
  }
  return JSON.parse(rawBody);
}

Stripe Sandbox Test Cards

Use these official Stripe test cards on https://payeny.com/pay/{cs_id} and https://payeny.com/portal/{session} with any future expiration date and any 3-digit CVC:

Card Number Scenario / Outcome
4242 4242 4242 4242 Success — Payment and subscription creation succeed immediately.
4000 0000 0000 0341 Attaches but fails on charge — Attaches to customer profile, fails when charged.
4000 0025 0000 3155 Requires 3DS — Triggers 3D Secure customer authentication challenge.
4000 0000 0000 9995 Insufficient funds — Declines immediately with insufficient_funds error.