Skip to main content
Charge customers who have already completed a payment with PayNext. Their payment method is securely stored, so you can process additional charges without collecting card details again.

​
When You Need This

  • Sell add-ons, credits, or one-time purchases to existing customers
  • Upgrade or downgrade subscription plans
  • Recover failed subscription payments
  • Process charges without showing checkout UI

​
Decision Flowchart

Key difference: SDK Checkout automatically prompts the customer to update their card if payment fails. API-Only charges require you to notify the customer separately.

​
Choose Your Approach

I want to…ApproachBest For
Show checkout and let customer confirmSDK CheckoutMost scenarios—automatic card update on failure
Charge silently without UIAPI-Only ChargesSilent plan changes, automated billing
Use SDK checkout when possible. If payment fails, the customer can immediately update their card—significantly improving success rates.

​
SDK Checkout

Display checkout with the customer’s saved payment method. If payment fails, they can switch to a new card instantly.

​
Client Session Parameters

Use CaseParametersResult
One-time paymentcustomer.id + plan.idPayment only
Change subscription plancustomer.id + plan.id + subscription.id + proration_billing_modePlan updated + payment
Recover past-duecustomer.id + subscription.idSubscription reactivated
For plan changes, include both the new plan.id and the existing subscription.id. For recovery, omit plan.id—PayNext uses the subscription’s current plan.

​
Example: One-Time Charge

cURL
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" },
    "options": { "payment_methods_mode": "saved_or_new" }
  }'
Then mount the SDK with the returned session id: 
const checkout = new PayNextCheckout()

checkout.mount('checkout-container', {
  clientToken: session.id,
  environment: 'sandbox',
  onCheckoutComplete: (result) => {
    console.log('Payment successful:', result.payment_id)
  },
  onCheckoutFail: (error) => {
    // Customer can retry with a different card in the SDK
    console.error('Payment failed:', error.status_reason?.message)
  }
})

​
Payment Method Display

ModeBehavior
saved_or_new (default)Show saved card, allow switching to new
new_onlyCollect new card only
Shows the customer’s saved card with an option to add a new one.

Demo: saved_or_new checkout flow

Animated demo coming soon

​
API-Only Charges

Charge a customer’s saved payment method without displaying checkout UI. PayNext processes synchronously and returns the result immediately.
Not recommended for most use cases. If payment fails, you must notify the customer and get them back to your UI to update their card. SDK checkout handles this automatically.

​
When to Use

ScenarioExample
One-time payment or new subscriptionAdd-ons, credits, or start subscription without UI
Change subscription planSilent plan upgrade/downgrade with immediate charge

​
Create a Charge

cURL
curl -X POST https://api.paynext.com/payments \
  -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"
  }'
Response: 
{
  "id": "pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789",
  "payment_status": "SETTLED",
  "amount": 1999,
  "currency_code": "USD",
  "payment_type": "MIT",
  "customer": {
    "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528"
  },
  "payment_method": {
    "id": "pm_d3b07384-d9a5-4d16-a5b1-3fa3d9b0b123",
    "type": "CARD",
    "details": {
      "last4": "4242",
      "brand": "visa"
    }
  }
}

​
Handle Failures

When a charge fails, check the advice_code to determine next steps. See Decline Codes for the full list.
For plan changes without immediate payment, use the Schedule Plan Change API instead—no charge occurs until the next billing date.

​
Subscription Renewals

PayNext automatically handles subscription renewals—you don’t need to create charges manually. Use the approaches above only for:
  • One-time purchases (add-ons, credits)
  • Silent plan upgrades/downgrades
  • Manual recovery after failed renewals
For failed subscription renewals, PayNext moves the subscription to past_due. Use Recover Subscriptions to collect payment with customer interaction.