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:
Copy
# 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:
Copy
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:
Copy
{
"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
Health Check
Check API and platform operational status.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/health \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/health');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/health', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/health',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Platform operational
Payments & Charges
List Payments
List all charges and payments for the authenticated merchant.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/payments \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/payments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/payments', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/payments',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of payments
400
401
404
429
Create Payment
Create a direct charge or authorization.
Request Body (Request JSON payload)
Field Type Required Description
amount_centsinteger yes
currencystring no
customer_idstring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/payments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_d0zigp0i',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"amount_cents" => 2900,
"currency" => "usd",
"customer_id" => "cus_3a1b2c3d4e5f"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/payments', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_vcf00xx9',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"amount_cents": 2900,
"currency": "usd",
"customer_id": "cus_3a1b2c3d4e5f"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/payments',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_br4i22xi',
'Content-Type': 'application/json'
},
json={
"amount_cents": 2900,
"currency": "usd",
"customer_id": "cus_3a1b2c3d4e5f"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Payment created
400
401
409
422
429
Retrieve Payment
Retrieve details for a specific payment, including checkout_session_id link.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/payments/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/payments/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/payments/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/payments/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Payment object
400
401
404
429
Checkout Sessions
List Payment Methods
Lists supported and attached payment methods for the merchant or a specific customer.
Parameters
Name In Type Required Description
customer_idquery string no Optional customer ID to list attached methods for.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/payment_methods -H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/payment_methods');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/payment_methods', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/payment_methods',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Response (200 OK)
Copy
{
"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
Status Description
200 List of payment methods
401 Missing or invalid secret key
List Checkout Sessions
Retrieve a list of checkout sessions for the authenticated merchant.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/checkout_sessions \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/checkout_sessions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/checkout_sessions', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/checkout_sessions',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of checkout sessions
400
401
404
429
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)
Field Type Required Description
modestring no payment (default) or subscription
amount_centsinteger no Required for mode=payment if no price_id
currencystring no Three-letter ISO currency code (e.g. usd)
success_urlstring yes Required. 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_urlstring yes Required. 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_idstring no Optional merchant order or reference ID
customer_emailstring no Optional customer email address
line_itemsarray no Optional array of line items
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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": []
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/checkout_sessions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_yeetseu4',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"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" => []
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/checkout_sessions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_izc0g83p',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"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": []
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/checkout_sessions',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_2qws995w',
'Content-Type': 'application/json'
},
json={
"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": []
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Checkout session created
400
401
409
422
429
Retrieve Checkout Session
Retrieve details for a specific checkout session.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/checkout_sessions/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/checkout_sessions/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/checkout_sessions/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/checkout_sessions/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Session details
400
401
404
429
Subscriptions & Recurring
List Subscriptions
List active and historical subscriptions.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/subscriptions \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/subscriptions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/subscriptions', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/subscriptions',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of subscriptions
400
401
404
429
Create Subscription
Create a recurring billing subscription.
Request Body (Request JSON payload)
Field Type Required Description
customer_idstring yes Customer ID (cus_...)
price_idstring yes Recurring catalog price ID (price_...)
payment_methodstring no Optional Stripe payment method ID or test token (e.g., pm_card_visa).
trial_period_daysinteger no Optional trial duration in days (0 to 730).
couponstring no Optional coupon ID or promotion code (e.g., ELEPT20OFF). Returns HTTP 400 invalid_coupon if invalid.
use_test_clockboolean no Test-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 | boolean no Test-mode only: optional Stripe Test Clock ID (clock_...) or boolean flag to attach to the customer and subscription.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/subscriptions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_x3pzvdy1',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"customer_id" => "cus_3a1b2c3d4e5f",
"price_id" => "pri_pro_monthly"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/subscriptions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_kd9etsvu',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"customer_id": "cus_3a1b2c3d4e5f",
"price_id": "pri_pro_monthly"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/subscriptions',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_8fk96cje',
'Content-Type': 'application/json'
},
json={
"customer_id": "cus_3a1b2c3d4e5f",
"price_id": "pri_pro_monthly"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Subscription created
400
401
409
422
429
Retrieve Subscription
Retrieve subscription status.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/subscriptions/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/subscriptions/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/subscriptions/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/subscriptions/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Subscription details
400
401
404
429
Change subscription plan/price
Updates an active subscription to a new recurring price.
Parameters
Name In Type Required Description
idpath string yes Subscription ID (sub_...)
Request Body (Request JSON payload)
Field Type Required Description
price_idstring yes
proration_behaviorstring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/subscriptions/sample_id/change_plan');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_f0p0orkl',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"price_id" => "price_abc123",
"proration_behavior" => "sample_proration_behavior"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/subscriptions/sample_id/change_plan', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_l5lxoriy',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"price_id": "price_abc123",
"proration_behavior": "sample_proration_behavior"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/subscriptions/sample_id/change_plan',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_nxegswyg',
'Content-Type': 'application/json'
},
json={
"price_id": "price_abc123",
"proration_behavior": "sample_proration_behavior"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Subscription plan updated
400
401
404 Subscription or price not found
409
422
429
Cancel a subscription
Cancels an active subscription immediately or at the current billing period end.
Parameters
Name In Type Required Description
idpath string yes Subscription ID (sub_...)
Request Body (Request JSON payload)
Field Type Required Description
cancel_at_period_endboolean no
immediateboolean no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/subscriptions/sample_id/cancel');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_ed1uzyfx',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"cancel_at_period_end" => false,
"immediate" => true
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/subscriptions/sample_id/cancel', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_6pdbq3yo',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"cancel_at_period_end": false,
"immediate": true
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/subscriptions/sample_id/cancel',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_u6zqm1w5',
'Content-Type': 'application/json'
},
json={
"cancel_at_period_end": false,
"immediate": true
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Subscription canceled
400
401
404 Subscription not found
409
422
429
Cancel a subscription (DELETE)
Cancels an active subscription immediately via HTTP DELETE (equivalent to POST /subscriptions/{id}/cancel).
Parameters
Name In Type Required Description
idpath string yes Subscription ID (sub_...)
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X DELETE https://payeny.com/api/v1/subscriptions/sub_sample_123 -H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/subscriptions/sub_sample_123');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/subscriptions/sub_sample_123', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.delete(
'https://payeny.com/api/v1/subscriptions/sub_sample_123',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Response (200 OK)
Copy
{
"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
Status Description
200 Subscription canceled
400 Invalid cancellation parameters
401 Missing or invalid secret key
404 Subscription not found
Resume a subscription
Resumes a subscription scheduled for cancellation at period end.
Parameters
Name In Type Required Description
idpath string yes Subscription ID (sub_...)
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/subscriptions/sample_id/resume');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_xqgureu0',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"status" => "active"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/subscriptions/sample_id/resume', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_88z8rxgg',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"status": "active"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/subscriptions/sample_id/resume',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_90qu7flz',
'Content-Type': 'application/json'
},
json={
"status": "active"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Subscription resumed
400
401
404 Subscription not found
409
422
429
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.
Copy
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"}'
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.
Copy
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}'
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".
Copy
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"}'
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.
Copy
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"}'
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)
Field Type Required Description
customer_idstring yes
return_urlstring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/billing_portal_sessions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_s8cj2n8x',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"customer_id" => "cus_0f2d32a8d5c63d658c60",
"return_url" => "https://example.com/account"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/billing_portal_sessions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_ov7rx9la',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"customer_id": "cus_0f2d32a8d5c63d658c60",
"return_url": "https://example.com/account"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/billing_portal_sessions',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_67tnfnvt',
'Content-Type': 'application/json'
},
json={
"customer_id": "cus_0f2d32a8d5c63d658c60",
"return_url": "https://example.com/account"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Billing portal session created
400
401
409
422
429
Customers
List Customers
List all customer accounts.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/customers \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/customers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/customers', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/customers',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of customers
400
401
404
429
Create Customer
Create a new customer profile.
Request Body (Request JSON payload)
Field Type Required Description
emailstring yes
namestring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/customers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_70f828qn',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"email" => "buyer@example.com",
"name" => "Jane Doe"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/customers', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_2hjecaqn',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"email": "buyer@example.com",
"name": "Jane Doe"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/customers',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_2jcvdnmw',
'Content-Type': 'application/json'
},
json={
"email": "buyer@example.com",
"name": "Jane Doe"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Customer created
400
401
409
422
429
Retrieve Customer
Retrieve customer profile.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/customers/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/customers/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/customers/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/customers/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Customer details
400
401
404
429
Update a customer
Updates name, email, or metadata on a customer profile.
Parameters
Name In Type Required Description
idpath string yes
Request Body (Request JSON payload)
Field Type Required Description
namestring no
emailstring no
phonestring no
metadataobject no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/customers/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_z6z4i6z8',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"name" => "Jane Doe",
"email" => "jane.doe@example.com",
"phone" => "+15555550199",
"metadata" => "sample_metadata"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/customers/sample_id', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_e24gs768',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "Jane Doe",
"email": "jane.doe@example.com",
"phone": "+15555550199",
"metadata": "sample_metadata"
})
});
const data = await response.json();
Copy
import requests
response = requests.patch(
'https://payeny.com/api/v1/customers/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_sd0bwf9v',
'Content-Type': 'application/json'
},
json={
"name": "Jane Doe",
"email": "jane.doe@example.com",
"phone": "+15555550199",
"metadata": "sample_metadata"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Customer updated
400
401
404 Customer not found
409
422
429
Products & Prices
List Products
List all merchant catalog products.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/products \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/products');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/products', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/products',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of products
400
401
404
429
Create Product
Create a new catalog product.
Request Body (Request JSON payload)
Field Type Required Description
namestring yes
descriptionstring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/products');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_jzh620io',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"name" => "Cloud Storage Sync Plan",
"description" => "Object sync package"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/products', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_0a6ubtu0',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "Cloud Storage Sync Plan",
"description": "Object sync package"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/products',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_cu1k5eip',
'Content-Type': 'application/json'
},
json={
"name": "Cloud Storage Sync Plan",
"description": "Object sync package"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Product created
400
401
409
422
429
Retrieve Product
Retrieve product catalog item.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/products/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/products/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/products/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/products/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Product details
400
401
404
429
Update a product
Updates specific fields on an existing product catalog item.
Parameters
Name In Type Required Description
idpath string yes
Request Body (Request JSON payload)
Field Type Required Description
namestring no
descriptionstring no
activeboolean no
metadataobject no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/products/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_jse3i9vr',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"name" => "Pro Membership",
"description" => "Updated membership details",
"active" => true,
"metadata" => "sample_metadata"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/products/sample_id', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_6x55hfto',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "Pro Membership",
"description": "Updated membership details",
"active": true,
"metadata": "sample_metadata"
})
});
const data = await response.json();
Copy
import requests
response = requests.patch(
'https://payeny.com/api/v1/products/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_mwikuckn',
'Content-Type': 'application/json'
},
json={
"name": "Pro Membership",
"description": "Updated membership details",
"active": true,
"metadata": "sample_metadata"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Product updated
400
401
404 Product not found
409
422
429
List Prices
List all pricing plans.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/prices \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/prices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/prices', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/prices',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of prices
400
401
404
429
Create Price
Create a one-time or recurring price plan.
Request Body (Request JSON payload)
Field Type Required Description
product_idstring yes
unit_amountinteger yes
currencystring no
typestring no
intervalstring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/prices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_7kcygl0v',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"product_id" => "prod_sample_sync",
"unit_amount" => 2900,
"currency" => "usd",
"type" => "recurring",
"interval" => "month"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/prices', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_7gigq9or',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"product_id": "prod_sample_sync",
"unit_amount": 2900,
"currency": "usd",
"type": "recurring",
"interval": "month"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/prices',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_a27xiuc6',
'Content-Type': 'application/json'
},
json={
"product_id": "prod_sample_sync",
"unit_amount": 2900,
"currency": "usd",
"type": "recurring",
"interval": "month"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Price created
400
401
409
422
429
Retrieve Price
Retrieve details for a price.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/prices/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/prices/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/prices/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/prices/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Price details
400
401
404
429
Update a price
Updates an existing price record.
Parameters
Name In Type Required Description
idpath string yes
Request Body (Request JSON payload)
Field Type Required Description
activeboolean no
nicknamestring no
metadataobject no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/prices/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_b4z9deqb',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"active" => true,
"nickname" => "Updated Monthly Pro",
"metadata" => "sample_metadata"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/prices/sample_id', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_kxkzbfwh',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"active": true,
"nickname": "Updated Monthly Pro",
"metadata": "sample_metadata"
})
});
const data = await response.json();
Copy
import requests
response = requests.patch(
'https://payeny.com/api/v1/prices/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_h2ia651u',
'Content-Type': 'application/json'
},
json={
"active": true,
"nickname": "Updated Monthly Pro",
"metadata": "sample_metadata"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Price updated
400
401
404 Price not found
409
422
429
Invoices
List Invoices
List invoices for the authenticated merchant.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/invoices \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/invoices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/invoices', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/invoices',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of invoices
400
401
404
429
Retrieve Invoice
Retrieve invoice record.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/invoices/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/invoices/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/invoices/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/invoices/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Invoice details
400
401
404
429
Download invoice PDF
Downloads the printable PDF or invoice rendering for a given invoice.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/invoices/sample_id/pdf \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/invoices/sample_id/pdf');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/invoices/sample_id/pdf', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/invoices/sample_id/pdf',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Invoice receipt PDF document
400
401
404 Invoice not found
429
Refunds
List Refunds
List refunds issued by the merchant.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/refunds \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/refunds');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/refunds', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/refunds',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of refunds
400
401
404
429
Create Refund
Issue a refund for a previously captured payment.
Request Body (Request JSON payload)
Field Type Required Description
payment_idstring yes
amount_centsinteger no Optional partial amount. Full amount refunded if omitted.
reasonstring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/refunds');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_c4u73sg6',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"payment_id" => "pay_356c860bac52fa30ec10",
"amount_cents" => 1000,
"reason" => "requested_by_customer"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/refunds', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_nueb59rl',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"payment_id": "pay_356c860bac52fa30ec10",
"amount_cents": 1000,
"reason": "requested_by_customer"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/refunds',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_bco2hzgt',
'Content-Type': 'application/json'
},
json={
"payment_id": "pay_356c860bac52fa30ec10",
"amount_cents": 1000,
"reason": "requested_by_customer"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Refund created
400
401
409
422
429
Retrieve Refund
Retrieve details of a refund.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/refunds/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/refunds/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/refunds/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/refunds/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Refund details
400
401
404
429
Events & Webhooks
List Events
List audit ledger events scoped to the merchant.
Parameters
Name In Type Required Description
typequery string no Filter by event type, e.g. checkout.completed
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/events \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/events');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/events', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/events',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of events
400
401
404
429
Retrieve Event
Retrieve an event from the audit ledger.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/events/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/events/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/events/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/events/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Event details
400
401
404
429
Resend Event
Redeliver an existing stored event to merchant webhooks using the same event ID.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/events/sample_id/resend');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_8fj8y47h',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"status" => "active"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/events/sample_id/resend', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_rd9q658g',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"status": "active"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/events/sample_id/resend',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_1mxexcz3',
'Content-Type': 'application/json'
},
json={
"status": "active"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Event redelivered
400
401
404
409
422
429
Resend a Webhook Delivery
Redelivers an existing webhook event delivery to the merchant endpoint without creating duplicate event records.
Parameters
Name In Type Required Description
idpath string yes Webhook delivery ID (del_...)
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X POST https://payeny.com/api/v1/webhook_deliveries/del_sample_123/resend -H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/webhook_deliveries/del_sample_123/resend');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/webhook_deliveries/del_sample_123/resend', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/webhook_deliveries/del_sample_123/resend',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Response (200 OK)
Copy
{
"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
Status Description
200 Webhook delivery re-queued
401 Missing or invalid secret key
List Webhook Endpoints
List registered webhook endpoints for the authenticated merchant.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/webhook_endpoints \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/webhook_endpoints');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/webhook_endpoints', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/webhook_endpoints',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of webhook endpoints
400
401
404
429
Create Webhook Endpoint
Register a new webhook URL (must be https). Returns the signing secret (whsec_) once only.
Request Body (Request JSON payload)
Field Type Required Description
urlstring yes
descriptionstring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/webhook_endpoints');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_u52ay1w2',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"url" => "https://example.com/webhooks/payeny",
"description" => "Production Webhook"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/webhook_endpoints', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_3kn74poj',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"url": "https://example.com/webhooks/payeny",
"description": "Production Webhook"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/webhook_endpoints',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_6u6lni6v',
'Content-Type': 'application/json'
},
json={
"url": "https://example.com/webhooks/payeny",
"description": "Production Webhook"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Webhook endpoint created
400
401
409
422
429
Delete Webhook Endpoint
Remove a registered webhook endpoint.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X DELETE https://payeny.com/api/v1/webhook_endpoints/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/webhook_endpoints/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/webhook_endpoints/sample_id', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.delete(
'https://payeny.com/api/v1/webhook_endpoints/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Webhook endpoint deleted
400
401
404
429
Retrieve Webhook Endpoint
Retrieve details of a registered webhook endpoint scoped to the merchant.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/webhook_endpoints/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/webhook_endpoints/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/webhook_endpoints/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/webhook_endpoints/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Webhook endpoint details
400
401
404
429
Connect Accounts & Onboarding
List Connect Accounts
List marketplace Connect accounts.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/connect/accounts \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/connect/accounts');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/connect/accounts', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/connect/accounts',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of connect accounts
400
401
404
429
Create Connect Account
Provision a new Connect standard or express account.
Request Body (Request JSON payload)
Field Type Required Description
emailstring yes
business_namestring no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/connect/accounts');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_8giyq6ri',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"email" => "seller@example.com",
"business_name" => "Seller Co"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/connect/accounts', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_2okl5byn',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"email": "seller@example.com",
"business_name": "Seller Co"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/connect/accounts',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_2ek0kimo',
'Content-Type': 'application/json'
},
json={
"email": "seller@example.com",
"business_name": "Seller Co"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Connect account created
400
401
409
422
429
Retrieve Connect Account
Retrieve account details and capability statuses.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/connect/accounts/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/connect/accounts/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/connect/accounts/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/connect/accounts/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Account details
400
401
404
429
Create Account Link
Create an onboarding or dashboard account link for a connected seller.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/connect/accounts/sample_id/account_links');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_xnnytky8',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"status" => "active"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/connect/accounts/sample_id/account_links', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_tydp8xjt',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"status": "active"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/connect/accounts/sample_id/account_links',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_l7pkgze9',
'Content-Type': 'application/json'
},
json={
"status": "active"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Account link URL
400
401
404
409
422
429
Create Onboarding Session
Create an embedded onboarding session for a connected account.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/connect/accounts/sample_id/onboarding_session');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_6nflobzo',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"status" => "active"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/connect/accounts/sample_id/onboarding_session', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_v987f8xv',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"status": "active"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/connect/accounts/sample_id/onboarding_session',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_ix2b82oe',
'Content-Type': 'application/json'
},
json={
"status": "active"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Onboarding session token and URL
400
401
404
409
422
429
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
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/connect/accounts/sample_id/verify-sandbox');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_n286rn1b',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"status" => "active"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/connect/accounts/sample_id/verify-sandbox', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_5475rww2',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"status": "active"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/connect/accounts/sample_id/verify-sandbox',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_tn636erc',
'Content-Type': 'application/json'
},
json={
"status": "active"
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Account verified in sandbox
400
401
404
409
422
429
Merchants
List Connected Merchants
List connected merchant accounts accessible to the caller.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/merchants \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/merchants');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/merchants', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/merchants',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of merchants
400
401
404
429
Create Merchant
Register a new connected merchant.
Request Body (Request JSON payload)
Field Type Required Description
namestring yes
emailstring yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/merchants');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_61vythcd',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"name" => "Partner Merchant",
"email" => "partner@example.com"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/merchants', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_llhn9gek',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "Partner Merchant",
"email": "partner@example.com"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/merchants',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_sv4e7piw',
'Content-Type': 'application/json'
},
json={
"name": "Partner Merchant",
"email": "partner@example.com"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Merchant registered
400
401
409
422
429
Retrieve Merchant
Retrieve details for a specific merchant.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/merchants/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/merchants/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/merchants/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/merchants/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Merchant details
400
401
404
429
Transactions & Balance
List marketplace transactions
Returns a list of marketplace order and payment transactions.
Parameters
Name In Type Required Description
limitquery integer no
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/transactions \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/transactions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/transactions', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/transactions',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of transactions
400
401
404
429
Retrieve a transaction
Retrieves details for a specific marketplace transaction.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/transactions/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/transactions/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/transactions/sample_id', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/transactions/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Transaction details
400
401
404 Transaction not found
429
Retrieve merchant balance
Returns available and pending ledger balances for the authenticated merchant.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/balance \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/balance');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/balance', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/balance',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Merchant balance
400
401
404
429
Redirect Domains
Trace Payout Settlement & Transit
Retrieves real-time settlement and banking transit lifecycle status for a payout or balance sweep.
Parameters
Name In Type Required Description
idpath string yes Payout ID (po_...)
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/payouts/sample_id/trace -H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/payouts/sample_id/trace');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/payouts/sample_id/trace', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/payouts/sample_id/trace',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Response (200 OK)
Copy
{
"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
Status Description
200 Payout trace events returned
401 Missing or invalid secret key
List Allowed Redirect Domains
List allowlisted hostnames permitted for checkout success_url and cancel_url.
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/allowed_redirect_domains \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/allowed_redirect_domains');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/allowed_redirect_domains', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/allowed_redirect_domains',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 List of allowed domains
400
401
404
429
Add Allowed Redirect Domain
Allowlist a bare hostname or explicit wildcard subdomain (*.example.com).
Request Body (Request JSON payload)
Field Type Required Description
domainstring yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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"
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/allowed_redirect_domains');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Idempotency-Key: idem_ov3rzayh',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
"domain" => "example.com"
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/allowed_redirect_domains', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_y19r6lov',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"domain": "example.com"
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/allowed_redirect_domains',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Idempotency-Key': 'idem_rz5twf3l',
'Content-Type': 'application/json'
},
json={
"domain": "example.com"
}
)
data = response.json()
Responses & Error Codes
Status Description
201 Domain added to allowlist
400
401
409
422
429
Delete Allowed Redirect Domain
Remove a domain from the allowlist.
Parameters
Name In Type Required Description
idpath string yes
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
curl -X DELETE https://payeny.com/api/v1/allowed_redirect_domains/sample_id \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/allowed_redirect_domains/sample_id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/allowed_redirect_domains/sample_id', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.delete(
'https://payeny.com/api/v1/allowed_redirect_domains/sample_id',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
Responses & Error Codes
Status Description
200 Domain removed from allowlist
400
401
404
429
Platform & Fee Architecture
Update Platform Fee Setting
Update the single platform fee setting ($0.25 flat fee single source of truth).
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/platform-fee');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
'platform_fee_cents' => 25,
'platform_fee_percent' => 0
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/platform-fee', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
platform_fee_cents: 25,
platform_fee_percent: 0
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/platform-fee',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Content-Type': 'application/json'
},
json={
'platform_fee_cents': 25,
'platform_fee_percent': 0
}
)
data = response.json()
Response (200 OK)
Copy
{
"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
Status Description
200 Platform fee updated
401 Missing or invalid secret key
List Disputes
Retrieve a list of payment disputes and chargebacks for the authenticated merchant.
Copy
curl -X GET https://payeny.com/api/v1/disputes \
-H "Authorization: Bearer sec_test_sample_key"
Retrieve Dispute
Retrieve details of a specific dispute or chargeback by ID.
Copy
curl -X GET https://payeny.com/api/v1/disputes/dp_sample_123 \
-H "Authorization: Bearer sec_test_sample_key"
Submit Dispute Evidence
Submit or stage dispute evidence (product description, customer communication, receipt, uncategorized text) for an open dispute/chargeback.
Parameters
Name In Type Required Description
idpath string yes Dispute identifier (dp_...).
product_descriptionbody string no Description of the product or service provided.
customer_namebody string no Customer full name.
customer_email_addressbody string no Customer email address.
uncategorized_textbody string no Additional supporting text evidence.
submitbody boolean no Whether to immediately submit the evidence to the card network (default true).
Executable Sandbox Samples
cURL
PHP
Node.js
Python
Copy
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
}'
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/disputes/dp_sample_123/evidence');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
'product_description' => 'Elept Pro Monthly SaaS Subscription',
'uncategorized_text' => 'Customer actively used the subscription.',
'submit' => true
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/disputes/dp_sample_123/evidence', {
method: 'POST',
headers: {
'Authorization': 'Bearer sec_test_sample_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
product_description: 'Elept Pro Monthly SaaS Subscription',
uncategorized_text: 'Customer actively used the subscription.',
submit: true
})
});
const data = await response.json();
Copy
import requests
response = requests.post(
'https://payeny.com/api/v1/disputes/dp_sample_123/evidence',
headers={
'Authorization': 'Bearer sec_test_sample_key',
'Content-Type': 'application/json'
},
json={
'product_description': 'Elept Pro Monthly SaaS Subscription',
'uncategorized_text': 'Customer actively used the subscription.',
'submit': True
}
)
data = response.json()
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
PHP
Node.js
Python
Copy
curl -X GET https://payeny.com/api/v1/api_keys \
-H "Authorization: Bearer sec_test_sample_key"
Copy
<?php
$ch = curl_init('https://payeny.com/api/v1/api_keys');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sec_test_sample_key'
]
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
Copy
const response = await fetch('https://payeny.com/api/v1/api_keys', {
method: 'GET',
headers: {
'Authorization': 'Bearer sec_test_sample_key'
}
});
const data = await response.json();
Copy
import requests
response = requests.get(
'https://payeny.com/api/v1/api_keys',
headers={
'Authorization': 'Bearer sec_test_sample_key'
}
)
data = response.json()
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
Copy
<?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
Copy
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.