Skip to main content
Display both local and payment currencies at checkout without managing currency formatting in your codebase. Add new currencies in PayNext Dashboard and they propagate instantly to your checkout.

​
Why Localize Pricing

No currency management

Don’t store currency symbols, decimal places, or formatting rules. PayNext handles it all.

Dashboard-controlled

Update pricing in the Dashboard. Changes propagate instantly to new checkout sessions.

100+ currencies

Automatic formatting for all currencies—including zero-decimal (JPY), two-decimal (USD), and three-decimal (IQD).

Better conversion

Localized pricing and rounded amounts improve checkout conversion rates.

​
How It Works

  1. Configure your plan in PayNext Dashboard with pricing and payment currency
  2. Create a client session with currency_details: true and the customer’s country
  3. Receive formatted amounts ready to display—no formatting logic needed
  4. Display in your checkout using formatted_amount values directly
When you update pricing in the Dashboard, your checkout copy adjusts automatically—no code changes required.

​
Enable Local Pricing

Add currency_details: true to your client session options: 
POST /client-session
{
  "customer": {
    "email": "[email protected]",
    "country": "US"
  },
  "plan": {
    "id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
  },
  "options": {
    "currency_details": true
  }
}
Currency details are optional. When disabled, responses remain lightweight without formatting data.

​
Response Structure

The currency_details.plan object contains pricing at two levels:
ObjectContainsDescription
plan.paymentPayment currencyPlan price in the currency configured in your plan
plan.localLocal currencyPlan price converted to customer’s local currency
plan.due_now.paymentPayment currencyAmount charged now in plan currency
plan.due_now.localLocal currencyAmount charged now in local currency

​
Example: Building Checkout Copy

Use the client session response to build professional checkout copy. Hover over to see which API field they come from.
Show the customer their local currency equivalent and inform them they’ll be charged in your payment currency:Your subscription will renew at every (charged ) automatically until you cancel.Total Today: for Trial
You’ll be charged . Full price starts after your trial ends on .

​
Exchange Rates

Exchange rates are markup-free and updated automatically by PayNext. You don’t need to manage exchange rate data in your application.

​
Rounded Prices

Rounded prices improve conversion rates. For example, $0.99 converts better than $0.71. The local object returns both options: 
{
  "local": {
    "formatted_amount": "$17.38",
    "formatted_amount_rounded": "$17.99"
  }
}
FieldExampleUse case
formatted_amount$17.38Exact conversion—use when precision matters
formatted_amount_rounded$17.99Rounded price—recommended for better conversion
We recommend using formatted_amount_rounded for checkout displays. Rounded prices feel more intentional and typically have higher conversion rates.
Building this in code: 
const { currency_details, plan } = clientSession;
const { local, payment, due_now } = currency_details.plan;

// Check if currencies are different
const showPaymentCurrency = local.currency !== payment.currency;

// Calculate trial end date
const trialEndDate = new Date(Date.now() + plan.trial.interval_count * 86400000);
const trialEndDateFormatted = trialEndDate.toLocaleDateString('en-US', { 
  month: 'long', 
  day: 'numeric', 
  year: 'numeric' 
});

// Build renewal text
let renewalText = `Your subscription will renew at ${local.formatted_amount_rounded} ${local.currency} every ${plan.interval_count} ${plan.interval}`;
if (showPaymentCurrency) {
  renewalText += ` (charged ${payment.formatted_amount} ${payment.currency})`;
}
renewalText += ' automatically until you cancel.';

// Build total today text
let totalText = `Total Today: ${due_now.local.formatted_amount_rounded} ${due_now.local.currency} for ${plan.trial.interval_count} ${plan.trial.interval} Trial\n`;
if (showPaymentCurrency) {
  totalText += `You'll be charged ${due_now.payment.formatted_amount} ${due_now.payment.currency}. `;
}
totalText += `Full price starts after your trial ends on ${trialEndDateFormatted}.`;

const checkoutCopy = `${renewalText}\n\n${totalText}`;
API response: 
{
  "currency_details": {
    "plan": {
      "payment": { "formatted_amount": "€15.00", "currency": "EUR" },
      "local": { "formatted_amount": "$17.40", "formatted_amount_rounded": "$17.99", "currency": "USD" },
      "due_now": {
        "payment": { "formatted_amount": "€1.00", "currency": "EUR" },
        "local": { "formatted_amount": "$1.16", "formatted_amount_rounded": "$1.49", "currency": "USD" }
      }
    }
  },
  "plan": {
    "interval": "month",
    "interval_count": 1,
    "trial": {
      "interval": "days",
      "interval_count": 7
    }
  }
}

​
Currency Formatting Reference

Different currencies have different formatting rules. PayNext handles this automatically: 
{
  "amount": 2000,
  "currency": "JPY",
  "currency_decimals": 0,
  "currency_symbol": "¥",
  "formatted_amount": "¥2000"
}
// 2000 minor units = ¥2000

​
Response Fields Reference

​
currency_details
object
Currency-specific pricing and display information.