How country_locked affects Checkout country, currency, and payment method availability

When country_locked=true is set on an order, the order country is fixed at creation time. This also fixes the country-specific pricing and currency used for that order in Checkout.

As a result, the player cannot switch to another country at Checkout, even if they are paying with a card or payment method issued in a different country.

What happens when country_locked=true

• The order country is locked to the country used when the order was created.
• The order currency stays tied to that country and price matrix.
• Checkout shows only payment methods available for that locked country.
• If a payment method does not support the combination of the locked order currency/country and the player’s actual payment instrument, the payment may be declined.

What happens when country_locked is disabled

If country_locked is disabled, the player can be prompted to switch country at Checkout when they choose a payment method that does not match the order’s current country.

• If the player agrees, Checkout switches the country.
• The price and currency are recalculated according to the price matrix for the new country.
• The payment method can then proceed using the updated country and currency.
• If the player declines the country change, the incompatible payment method remains unavailable.

Checkout vs Hub behavior

This behavior applies to Checkout orders that use the country_locked flag.

Payments made through Hub do not fix the country in the same way, so you may see a player succeed in Hub while the same player fails in Checkout when country_locked=true is enabled.

Typical use case

Use country_locked=true only if you intentionally want to prevent country and currency changes after order creation. If you want Checkout to adapt to the player’s actual payment country and available methods, leave country_locked disabled.

Troubleshooting

If a player reports that a payment started failing after previously working:

1. Check whether country_locked=true is being set for Checkout orders.
2. Check which country is being sent when the order is created.
3. Verify whether the player is trying to pay with a method from a different country than the order country.
4. Compare the same player flow in Checkout versus Hub, because Hub payments may still work when Checkout is country-locked.

A common symptom is a player with a UK payment method being unable to complete payment on a USD order created for another country, while the same player succeeds when the order country is not locked.