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

Payeny REST API Reference (v1)

Complete developer reference for the Payeny Sandbox Payment Infrastructure. Everything in the developer sandbox runs strictly in Stripe TEST mode (PAYENY_MODE=sandbox).

1. Quickstart (3 Steps to First Sandbox Charge)

  1. Authenticate with your Merchant Test Key: Grab your tenant's sec_test_... key from /admin/merchants and pass it via Authorization: Bearer sec_test_....
  2. Create a Product, Price & Checkout Session: Call POST /api/v1/products, POST /api/v1/prices, and POST /api/v1/checkout_sessions with your allowlisted https:// success_url and cancel_url.
  3. Complete Checkout & Verify Webhook: Redirect the user to the returned https://payeny.com/pay/{cs_id} URL, pay with Stripe test card 4242 4242 4242 4242, and verify the signed checkout.completed webhook via Payeny-Signature.
Base URL: https://payeny.com/api/v1

2. Authentication, Error Format & Idempotency

Each merchant tenant has an isolated publishable key (pub_test_...) and secret key (sec_test_...). Secret keys are stored hashed with SHA-256 and a server-side pepper. Payeny resolves the calling merchant from the Authorization: Bearer header on every request. While in sandbox mode, any sec_live_... key is rejected with HTTP 401, and if any loaded Stripe key does not start with pk_test_ or sk_test_, payment routes refuse to boot and return HTTP 503 (non_test_key_in_sandbox).

Standard Error Response Envelope
{
  "success": false,
  "error": {
    "type": "validation_error",
    "code": "invalid_success_url",
    "message": "The 'success_url' must be an https URL on an allowlisted domain for this merchant.",
    "param": "success_url"
  },
  "request_id": "req_4a3b2c1d0e9f8a7b",
  "livemode": false
}
Status Error type Description
200 / 201 data envelope Returns {"data":{...},"request_id":"req_...","livemode":false}.
400 bad_request / invalid_request_error Malformed JSON payload, missing required parameter, or unrecognized/inactive coupon (code: "invalid_coupon").
401 unauthorized Missing, invalid, revoked, or sec_live_ API key in sandbox.
403 invalid_request_error Code test_mode_only: Sandbox test helpers (POST /api/v1/subscriptions/{id}/advance_clock and POST /api/v1/events/{id}/replay) refuse execution in live mode.
404 not_found / not_found_error Route or resource ID does not exist for the calling merchant.
409 idempotency_conflict Same Idempotency-Key reused with a different request body within 24h.
422 validation_error / invalid_request_error Domain allowlist check failed, invalid field value, or refund attempted on a disputed payment (code: "payment_disputed").
503 configuration_error Code non_test_key_in_sandbox: non-test Stripe key detected in sandbox mode.
Idempotency (Idempotency-Key Header): Every POST endpoint accepts an Idempotency-Key header. Payeny stores key + merchant + request_hash + response for 24 hours and passes the key through to Stripe. Replaying the same key with the same body returns the cached response; reusing the same key with a different body returns HTTP 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"