Documentation Index
Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
Use this file to discover all available pages before exploring further.
Quick reference for SDK client session parameters when charging returning customers. The SDK behavior is identical for all scenarios—only the client session payload differs.
Use Cases
| Flow | Parameters | Result |
|---|
| One-time payment | customer.id + plan.id | Payment created, no subscription |
| Change plan | customer.id + plan.id + subscription.id | Subscription updated, payment collected |
| Recover past due | customer.id + subscription.id | Subscription reactivated |
One-Time Payment
Charge an existing customer for a one-time purchase (add-on, credits, standalone item).
Create Client Session
curl -X POST https://api.paynext.com/client-session \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-API-Version: 1.0.0" \
-H "Content-Type: application/json" \
-d '{
"customer": { "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528" },
"plan": { "id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d" },
"payment": { "metadata": { "order_id": "order_12345" } },
"options": { "payment_methods_mode": "saved_or_new" }
}'
The plan must have type: one_off. Do not include subscription for one-time payments.
Change Plan
Upgrade or downgrade a subscription with immediate payment.
Create Client Session
curl -X POST https://api.paynext.com/client-session \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-API-Version: 1.0.0" \
-H "Content-Type: application/json" \
-d '{
"customer": { "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528" },
"plan": { "id": "plan_8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e" },
"subscription": {
"id": "sub_11dfa45f-23b1-40f4-9e9b-c9d485915528",
"proration_billing_mode": "prorated_immediately"
},
"options": { "payment_methods_mode": "saved_or_new" }
}'
Proration Modes
| Mode | Behavior |
|---|
prorated_immediately | Charge difference based on remaining time, reset billing cycle |
full_immediately | Charge full new plan price, reset billing cycle |
Recover Past Due
Collect payment for failed renewals to reactivate a subscription.
Create Client Session
curl -X POST https://api.paynext.com/client-session \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-API-Version: 1.0.0" \
-H "Content-Type: application/json" \
-d '{
"customer": { "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528" },
"subscription": { "id": "sub_11dfa45f-23b1-40f4-9e9b-c9d485915528" },
"options": { "payment_methods_mode": "saved_or_new" }
}'
Do not include plan.id for recovery—PayNext uses the existing plan from the subscription.
Mount the SDK
Once you have the session id, mount the checkout:
'use client'
import { useEffect } from 'react'
import { PayNextCheckout } from '@paynext/sdk'
import '@paynext/sdk/styles'
export const SavedMethodCheckout = ({ sessionId }: { sessionId: string }) => {
useEffect(() => {
const checkout = new PayNextCheckout()
checkout.mount('paynext-checkout', {
clientToken: sessionId,
environment: 'sandbox',
onCheckoutComplete: (result) => {
console.log('Payment successful:', result.payment_id)
// Handle success
},
onCheckoutFail: (error) => {
console.error('Payment failed:', error.status_reason?.decline_code)
// Customer can switch cards and retry in the SDK
},
})
return () => checkout.unmount()
}, [sessionId])
return <div id="paynext-checkout" />
}
- SDK displays the customer’s saved payment method
- Customer can switch to a new card if needed
- On failure, customer retries instantly—no new session required
→ SDK Getting Started for full configuration options
Payment Method Modes
| Mode | Behavior |
|---|
saved_or_new (default) | Show saved card, allow switching to new |
new_only | Collect new card only, ignore saved methods |
Outcomes
| Result | One-Time | Change Plan | Recovery |
|---|
| Success | Payment created | Subscription updated, billing cycle reset | Subscription returns to active |
| Failure | Customer retries with new card | Subscription stays on old plan | Customer retries with new card |
