Local Currencies

This guide covers how to charge your users in their local currency. When you create an order with a local currency, the quote, the checkout, and the card charge are all denominated in the selected currency.

Available Currencies

Currency	Code	Availability
USD	`usd`	✅
EUR	`eur`	✅
GBP	`gbp`	✱
AUD	`aud`	✱
COP	`cop`	✱

*EUR, GBP, AUD, and COP are not available for US residents.

Legend:

✅ Supported
✱ Available, but not self-serve. Contact us to request it for your project.

If you are interested in a local currency that is not listed, contact Crossmint to confirm support.

Create the Order in the Selected Currency

From your server, pass the selected currency in payment.currency. With exact-in, amount is expressed in the payment currency, so "100" with "currency": "eur" means 100 EUR.

Recommended: pre-select the default currency from the user’s country of residence if your app already knows it, or from their IP address otherwise, and add a currency selector to your UI so the user can change it.

curl --request POST \
    --url https://staging.crossmint.com/api/2022-06-09/orders \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
    --data '{
        "recipient": { "walletAddress": "USER_WALLET_ADDRESS" },
        "lineItems": [{
            "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
            "executionParameters": { "mode": "exact-in", "amount": "100" }
        }],
        "payment": {
            "method": "card",
            "currency": "eur",
            "receiptEmail": "user@example.com"
        }
    }'

const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_SERVER_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        recipient: { walletAddress: "USER_WALLET_ADDRESS" },
        lineItems: [
            {
                tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                executionParameters: { mode: "exact-in", amount: "100" },
            },
        ],
        payment: {
            method: "card",
            currency: "eur",
            receiptEmail: "user@example.com",
        },
    }),
});
const { order, clientSecret } = await response.json();

import requests

response = requests.post(
    "https://staging.crossmint.com/api/2022-06-09/orders",
    headers={"X-API-KEY": "YOUR_SERVER_API_KEY", "Content-Type": "application/json"},
    json={
        "recipient": {"walletAddress": "USER_WALLET_ADDRESS"},
        "lineItems": [
            {
                "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "executionParameters": {"mode": "exact-in", "amount": "100"},
            }
        ],
        "payment": {"method": "card", "currency": "eur", "receiptEmail": "user@example.com"},
    },
)
print(response.json())

The response contains order.payment.currency: "eur" and a quote priced in EUR, for example order.quote.totalPrice: { "amount": "100", "currency": "eur" }. The amount of stablecoin the user receives is in order.lineItems[0].quote.quantityRange. If the user changes the currency after the order exists, update it from your server with a PATCH to /api/2022-06-09/orders/{orderId} and the new payment.currency, authenticated with your server-side API key. See Edit Order.

Onramp orders cannot be updated from the client side. Update requests authenticated with the order clientSecret are rejected. Use your server-side API key.

Render the Checkout in the Same Currency

Set payment.fiat.defaultCurrency on the checkout component to the currency you used to create the order. The checkout compares this value with the order currency and, if they differ, tries to update the order to match defaultCurrency. Because onramp orders cannot be updated from the client side, that request fails and the checkout shows an error to the user. The SDK default is usd, so always set it explicitly on a EUR order.

React
React Native
Swift
Kotlin

<CrossmintEmbeddedCheckout
    orderId={order.orderId}
    clientSecret={clientSecret}
    payment={{
        crypto: { enabled: false },
        fiat: {
            enabled: true,
            defaultCurrency: "eur",
            allowedMethods: { card: true, applePay: true, googlePay: true },
        },
    }}
/>

<CrossmintEmbeddedCheckout
    orderId={order.orderId}
    clientSecret={clientSecret}
    payment={{
        crypto: { enabled: false },
        fiat: {
            enabled: true,
            defaultCurrency: "eur",
            allowedMethods: { card: true, applePay: true, googlePay: true },
        },
    }}
/>

CheckoutPayment(
    crypto: CheckoutCryptoPayment(enabled: false),
    fiat: CheckoutFiatPayment(
        enabled: true,
        defaultCurrency: "eur",
        allowedMethods: CheckoutAllowedMethods(card: true, applePay: true)
    )
)

CheckoutPayment(
    crypto = CheckoutCryptoPayment(enabled = false),
    fiat = CheckoutFiatPayment(
        enabled = true,
        defaultCurrency = "eur",
        allowedMethods = CheckoutAllowedMethods(card = true, googlePay = true)
    )
)

Verify the Currency

Fetch the order with Get Order and confirm that payment.currency and quote.totalPrice.currency are both "eur". In the checkout, the price and the card charge are shown in EUR.

Troubleshooting

The checkout shows an error right after loading

payment.fiat.defaultCurrency on the checkout component does not match the currency of the order. The checkout tries to update the order from the client side, which is not allowed for onramp orders. Pass the same value you used in payment.currency when creating the order.

Order update fails with 'cannot be updated from client side auth'

You are updating an onramp order with the order clientSecret. Send the PATCH from your server with your server-side API key.

Order creation fails with payments:payment-currency.not-supported

The currency is not enabled for your project. The error response lists the currencies you can use in parameters.supportedCurrencies. To enable a non-self-serve currency (gbp, aud, cop), contact Crossmint.

Next Steps

Add Payment Methods

Enable cards, Apple Pay, and Google Pay for onramp

Import User KYC Data

Reuse the country of residence you already collected

Create Order

Full reference for the onramp order payload

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Available Currencies

Create the Order in the Selected Currency

Render the Checkout in the Same Currency

Verify the Currency

Troubleshooting

Next Steps

Add Payment Methods

Import User KYC Data

Create Order

​Available Currencies

​Create the Order in the Selected Currency

​Render the Checkout in the Same Currency

​Verify the Currency

​Troubleshooting

​Next Steps

Add Payment Methods

Import User KYC Data

Create Order

Available Currencies

Create the Order in the Selected Currency

Render the Checkout in the Same Currency

Verify the Currency

Troubleshooting

Next Steps