thelastapi
Get started free

Sell in multiple currencies

Accept payments in 35 currencies using thelastapi by defining localized prices or checkouts that settle directly into your project USD balance.

On this page 7 sections

You can accept payments in 35 currencies with thelastapi by specifying a currency code on your product prices or checkout requests. thelastapi acts as the merchant of record for your project, so you do not need to register separate foreign business entities or open international bank accounts to sell abroad. Every international transaction settles into your project balance in USD at the exchange rate of the day, allowing you to charge global customers in their local currency while keeping accounting simple.

This guide walks through how currency conversion works, how to configure multi-currency products and checkouts, and how to inspect settled funds in webhooks.

How multi-currency settlement works

When you create a project, card payments work right away. You do not need an identity check before selling, and there are no processor API keys to manage in your application code. For a broader overview of how our merchant setup operates, see how to take payments online without opening a merchant account.

thelastapi supports 35 currencies: usd, eur, gbp, cad, aud, nzd, chf, sek, nok, dkk, pln, czk, huf, ron, bgn, mxn, brl, cop, clp, pen, ars, jpy, krw, inr, sgd, hkd, twd, thb, myr, php, idr, zar, aed, ils, and try.

When a buyer checks out in a non-USD currency, the money moves through three stages:

  1. Buyer charge: The customer sees and pays the exact amount in their selected currency (such as €14.00 or ¥3,000).
  2. Processor conversion: The payment processor converts the foreign currency into USD at the current exchange rate, minus a standard currency-conversion fee (typically 1–2%).
  3. Ledger credit: Your project balance is credited in USD.

Your ledger tracks both the charged amount and the settled result. On each payment object, amount_cents and currency show what the customer paid, while settled_usd_cents shows the amount added to your balance. The transaction's fee_cents and net_cents are calculated in USD. You can read more about balance updates in Payments: how money moves.

Understanding currency units and charge minimums

All currency fields take lowercase ISO 4217 three-letter codes (such as eur, gbp, or jpy). When passing amount_cents or unit_amount_cents, provide the value in the currency's smallest unit:

  • Standard currencies: Provide amounts in cents. An amount_cents value of 1500 in eur represents €15.00.
  • Zero-decimal currencies: For jpy, krw, and clp, amounts represent whole units. An amount_cents value of 3000 in jpy charges ¥3,000.

Each currency enforces a minimum allowable transaction amount. If a checkout is created below this minimum, the API returns a 400 invalid_request error (such as amount 20 is below the 50 minimum for eur).

CurrencySmallest unitMinimum chargeCode exampleDisplay amount
usdCents501500$15.00
eurCents501400€14.00
gbpPence301200£12.00
cadCents502000CA$20.00
audCents502000A$20.00
jpyWhole unit503000¥3,000
mxnCents100025000MX$250.00

Setting up multi-currency products and prices

Catalogs are maintained separately per environment (development and production). Create and test your catalog in development first before creating products for live buyers.

To add a recurring plan priced in Euros with the CLI:

Terminal
vibiz payments products add "Pro EU" \
  --amount 1400 \
  --currency eur \
  --interval month \
  --lookup-key pro-monthly-eur \
  --dev

You can also create products over HTTP using your account key (vz_sk_...):

Terminal
curl https://thelastapi.dev/v1/projects/prj_123/payments/products?env=development \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Pro (EU)",
    "price": {
      "unit_amount_cents": 1400,
      "currency": "eur",
      "type": "recurring",
      "interval": "month",
      "lookup_key": "pro-monthly-eur"
    }
  }'

A subscription price bills in its defined currency. A single buyer cannot hold subscriptions in two different currencies at the same time; trying to add a second subscription in another currency returns a 409 conflict error with reason: currency_conflict. Learn more about configuring recurring plans in our guide to add a subscription checkout to a SaaS.

Creating checkouts in your application

When using the @vibiz/app package, your backend talks to thelastapi using the server-side secret VIBIZ_APP_KEY.

For recurring plans, pass the plan's lookup_key. The checkout page automatically adopts the currency attached to that price:

TypeScript
import { redirect } from 'next/navigation';
import { vibiz } from '@vibiz/app';

export async function upgradeAction(userId: string) {
  const { url } = await vibiz.payments.checkout({
    lookup_key: 'pro-monthly-eur',
    user: userId,
    success_url: 'https://example.com/billing/success',
    cancel_url: 'https://example.com/pricing',
    metadata: {
      tier: 'pro_eu',
    },
  });

  redirect(url);
}

For one-off payments without pre-configured products, set the currency parameter along with amount_cents and a name:

TypeScript
import { vibiz } from '@vibiz/app';

const { url } = await vibiz.payments.checkout({
  amount_cents: 3000,
  currency: 'jpy',
  name: 'Export Report',
  user: 'u_123',
  success_url: 'https://example.com/reports/success',
  cancel_url: 'https://example.com/reports',
});

Checkout links are valid for one buyer and expire after 1 hour. Never hard-code checkout links into static HTML templates. If you are selling digital downloads or physical goods from a static frontend, review how to sell from a static site with a checkout link. Full SDK details are documented in Payments in the app (@vibiz/app).

You can also customize the hosted checkout page with your own brand. Set name, logo_url, button_color, and font across the project using a PATCH request to /v1/projects/:id/payments, or pass a brand object directly inside the checkout request.

Tracking multi-currency payments with webhooks

When a checkout completes, thelastapi sends a payment.succeeded event to your registered webhook endpoint. Set your development webhook URL with the CLI:

Terminal
vibiz payments webhook http://localhost:3000/api/vibiz/webhook --dev

In your endpoint handler, verify the payload using @vibiz/app. It checks the Vibiz-Signature header against your signing secret automatically:

TypeScript
// app/api/vibiz/webhook/route.ts
import { vibiz } from '@vibiz/app';

export async function POST(req: Request) {
  let event;
  try {
    event = await vibiz.webhooks.receive(req);
  } catch {
    return new Response('bad signature', { status: 400 });
  }

  if (event.type === 'payment.succeeded') {
    const payment = event.data.object;

    // What the customer saw on their receipt
    console.log(`Charged: ${payment.amount_cents} ${payment.currency}`);

    // What arrived in your ledger in USD
    console.log(`Settled: $${payment.settled_usd_cents / 100} USD`);
    console.log(`Net USD: $${payment.net_cents / 100} USD`);
  }

  return new Response('ok');
}

You can test this flow locally using test-mode payment simulation:

Terminal
vibiz payments simulate payment --dev

For production deployments on thelastapi hosting or linked domains, webhooks automatically route to /api/vibiz/webhook. More details can be found in Webhooks: thelastapi tells the app when someone pays.

Handling refunds, holds, and bank withdrawals

Because the balance is held entirely in USD, you do not manage separate foreign currency balances. Withdrawing money follows a single flow:

  1. Holding period: In production, payments remain pending for 7 days (fees.hold_days) before becoming available for withdrawal. In development mode, there is no hold.
  2. Identity verification: The project owner completes identity verification and enters bank account details once under Payments ▸ Get paid in the console. Bank payouts are supported for owners in the US, Canada, the UK, the European Economic Area (EEA), and Switzerland.
  3. Withdrawals: The owner initiates a transfer using the console or the CLI:
Terminal
vibiz payments withdraw

If an international purchase is refunded, the amount deducted from your USD balance is calculated using the processor's exchange rate on the day of the refund. This means the refunded USD cost may vary slightly from the initial settled USD amount. Refunds do not return the card processing fee (2.9% + 30¢ for standard US cards) or the thelastapi platform fee. If your available and pending balance cannot cover the refund, the API returns a 409 conflict with insufficient_balance.

To start accepting international payments, create a development product using the CLI and verify the checkout flow in test mode. See the complete reference on the Payments documentation page.

Frequently asked questions

Can my project balance hold multiple currencies simultaneously?

No. Your balance is always held and tracked in USD. When a buyer pays in another currency, the processor converts the transaction to USD at the daily rate, minus a conversion fee of about 1–2%, and credits your ledger in USD.

What happens if a customer tries to buy two subscriptions in different currencies?

The API prevents a single user from holding subscriptions in multiple currencies. Attempting to create a second subscription for the same user in another currency returns a 409 conflict error with the reason currency_conflict.

How do zero-decimal currencies like Japanese Yen work in checkout calls?

Zero-decimal currencies such as JPY, KRW, and CLP use whole units rather than cents. Setting amount_cents to 3000 with currency set to jpy charges exactly ¥3,000.

Which countries can withdraw earnings from multi-currency sales?

Supported payout regions include the United States, Canada, the United Kingdom, countries in the European Economic Area (EEA), and Switzerland. Payouts are made directly to the bank account registered by the owner in the console.