Display Local Pricing

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

Configure your plan in PayNext Dashboard with pricing and payment currency
Create a client session with currency_details: true and the customer’s country
Receive formatted amounts ready to display—no formatting logic needed
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": "customer@example.com",
    "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:

Object	Contains	Description
`plan.payment`	Payment currency	Plan price in the currency configured in your plan
`plan.local`	Local currency	Plan price converted to customer’s local currency
`plan.due_now.payment`	Payment currency	Amount charged now in plan currency
`plan.due_now.local`	Local currency	Amount 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 both currencies
Hide redundant currency
Show only local

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 .

When local.currency equals payment.currency, hide the charged amount—it’s redundant:Your subscription will renew at every automatically until you cancel.Total Today: for Trial
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"
  }
}

Field	Example	Use case
`formatted_amount`	$17.38	Exact conversion—use when precision matters
`formatted_amount_rounded`	$17.99	Rounded 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

{
  "amount": 1999,
  "currency": "USD",
  "currency_decimals": 2,
  "currency_symbol": "$",
  "formatted_amount": "$19.99"
}
// 1999 minor units = $19.99

{
  "amount": 1500,
  "currency": "IQD",
  "currency_decimals": 3,
  "currency_position": "right",
  "currency_symbol": "د.ع",
  "formatted_amount": "1.500د.ع"
}
// 1500 minor units = 1.500 IQD

Response Fields Reference

object

Currency-specific pricing and display information.

Show Properties

object

Pricing information for the plan.

Show Properties

object

required

Plan price in payment currency—the recurring amount for future renewals.

Show Properties

integer

Amount in minor units (e.g., 1999 = $19.99).

string

ISO 4217 currency code (e.g., “USD”, “EUR”).

integer

Decimal places for this currency (0, 2, or 3).

string

Symbol position: “left” or “right”.

string

Currency symbol (e.g., ”$”, ”€”, ”¥”).

string

Ready-to-display formatted amount.

object

Local currency equivalent (included when customer’s country differs from payment currency).

Show Properties

integer

Amount in local currency minor units.

string

Local currency code.

number

Exchange rate from payment to local currency.

string

Formatted local amount.

string

Rounded formatted amount for cleaner display.

object

Amount charged now—trial price if enabled, or same as payment if no trial.

Show Properties

object

Due now in payment currency (same structure as plan.payment).

object

Due now in local currency (same structure as plan.local).

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

Why Localize Pricing

No currency management

Dashboard-controlled

100+ currencies

Better conversion

How It Works

Enable Local Pricing

Response Structure

Example: Building Checkout Copy

Exchange Rates

Rounded Prices

Currency Formatting Reference

Response Fields Reference

​Why Localize Pricing

No currency management

Dashboard-controlled

100+ currencies

Better conversion

​How It Works

​Enable Local Pricing

​Response Structure

​Example: Building Checkout Copy

​Exchange Rates

​Rounded Prices

​Currency Formatting Reference

​Response Fields Reference

Why Localize Pricing

How It Works

Enable Local Pricing

Response Structure

Example: Building Checkout Copy

Exchange Rates

Rounded Prices

Currency Formatting Reference

Response Fields Reference