Charge Returning Customers

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…	Approach	Best For
Show checkout and let customer confirm	SDK Checkout	Most scenarios—automatic card update on failure
Charge silently without UI	API-Only Charges	Silent 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 Case	Parameters	Result
One-time payment	`customer.id` + `plan.id`	Payment only
Change subscription plan	`customer.id` + `plan.id` + `subscription.id` + `proration_billing_mode`	Plan updated + payment
Recover past-due	`customer.id` + `subscription.id`	Subscription 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.

One-off plans accept a custom price: add plan.price ({ "amount", "currency" }) to the client session to override the plan’s amount for this checkout. See Custom Pricing.

Example: One-Time Charge

cURL

curl -X POST https://api.paynext.com/client-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.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

Mode	Behavior
`saved_or_new` (default)	Show saved card, allow switching to new
`new_only`	Collect new card only

saved_or_new
new_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

Scenario	Example
One-time payment or new subscription	Add-ons, credits, or start subscription without UI
Change subscription plan	Silent 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: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528",
    "plan_id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
  }'

Show Request parameters

Parameter	Required	Description
`customer_id`	Yes	PayNext customer ID
`plan_id`	Yes	Plan ID that defines amount and currency
`price`	No	Custom price `{ "amount", "currency" }` overriding the plan’s price. One-off plans only. See Custom Pricing
`subscription_id`	No	Include for plan changes
`proration_billing_mode`	No	Required with `subscription_id` for plan changes

Custom Pricing

For one-off plans, override the plan’s amount for this charge by adding a price object—useful for variable-amount purchases without a dedicated plan:

cURL

curl -X POST https://api.paynext.com/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528",
    "plan_id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "price": { "amount": 4999, "currency": "USD" }
  }'

amount is in minor units. The custom price overrides both the default and any localized pricing. Passing price with a recurring plan returns a 400 error.

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.

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

When You Need This

Decision Flowchart

Choose Your Approach

SDK Checkout

Client Session Parameters

Example: One-Time Charge

Payment Method Display

API-Only Charges

When to Use

Create a Charge

Custom Pricing

Handle Failures

Subscription Renewals

​When You Need This

​Decision Flowchart

​Choose Your Approach

​SDK Checkout

​Client Session Parameters

​Example: One-Time Charge

​Payment Method Display

​API-Only Charges

​When to Use

​Create a Charge

​Custom Pricing

​Handle Failures

​Subscription Renewals

When You Need This

Decision Flowchart

Choose Your Approach

SDK Checkout

Client Session Parameters

Example: One-Time Charge

Payment Method Display

API-Only Charges

When to Use

Create a Charge

Custom Pricing

Handle Failures

Subscription Renewals