The API uses four distinct code systems for country, dialing, and currency identification across fields whose naming is inconsistent enough to be a frequent source of integration errors. This page defines each system and maps every field in the published API to the correct convention.

Country codes: Alpha-2 vs Alpha-3

ISO 3166-1 defines countries in three formats: Alpha-2 (2-letter), Alpha-3 (3-letter), and Numeric (3-digit). The API uses two of these three in different fields:

Field	Object	Expects	Example	Reference
`placeOfBirth`	`CardholderCreate`, `CardholderUpdate`	Alpha-3	`USA`, `GBR`, `ARE`, `DEU`	ISO 3166-1 Alpha-3
`country`	`CardholderCreate`, `CardholderUpdate`	Alpha-2	`US`, `GB`, `AE`, `DE`	ISO 3166-1 Alpha-2
`countryCallingCode`	`CardholderCreate`, `CardholderUpdate`, card contact fields	Alpha-2	`US`, `GB`, `AE`, `DE`	ISO 3166-1 Alpha-2

🚧
Each of these fields expects a different code format — use the table above to confirm which convention applies before submitting cardholder data.

Selected Alpha-2 / Alpha-3 mappings

Country	Alpha-2	Alpha-3
United States	`US`	`USA`
United Kingdom	`GB`	`GBR`
United Arab Emirates	`AE`	`ARE`
European Union member states	Country-specific	Country-specific
Germany	`DE`	`DEU`
France	`FR`	`FRA`
Canada	`CA`	`CAN`
Australia	`AU`	`AUS`
Singapore	`SG`	`SGP`
Hong Kong	`HK`	`HKG`

For the complete list, refer to the IBAN ISO 3166 reference.

Calling codes: ITU dialing codes

The callingCode field expects an ITU international dialing code — the country prefix used when dialing internationally (e.g. 1 for the US, 44 for the UK).

Zero-padding requirement

❗️
callingCode must always be exactly 3 characters, zero-padded from the left. Pass 001 for the United States (not 1), 044 for the United Kingdom (not 44). Three-digit codes (e.g. 971 for the UAE, 852 for Hong Kong) require no padding and are passed as-is.

Country	ITU dialing code	Pass as `callingCode`
United States / Canada	1	`001`
United Kingdom	44	`044`
Germany	49	`049`
France	33	`033`
United Arab Emirates	971	`971`
Hong Kong	852	`852`
Singapore	65	`065`
Australia	61	`061`

For the complete list, see ITU-T E.164 dialing codes.

`countryCallingCode` is not a dialing code

Despite its name, countryCallingCode is an ISO 3166-1 Alpha-2 country code (e.g. US, GB), not a dialing code. It identifies the country for the phoneNum field (typically a landline). callingCode is the ITU dialing code for cellNum (mobile). The two fields form two separate phone number pairs:

Number field	Dialing/country code field	Format
`cellNum` (mobile)	`callingCode`	ITU dialing code, zero-padded to 3 digits
`phoneNum` (landline)	`countryCallingCode`	ISO 3166-1 Alpha-2 country code

Currency: integer enum

Currency in the API is represented as an integer enum, derived from the Program and never passed as a currency code string.

Integer	ISO 4217 code	Currency
`0`	USD	United States Dollar
`1`	CAD	Canadian Dollar
`2`	GBP	British Pound Sterling
`3`	EUR	Euro

See Accounts, Wallets & Deposit Addresses for the decimal-implied integer convention that governs all monetary amounts.

Amount convention: decimal-implied integers

All monetary fields in the API (balances, transaction limits, transfer amounts, deposit amounts) use decimal-implied integers: the integer value represents the amount in the smallest currency unit (cents for USD/CAD, pence for GBP, euro-cents for EUR):

Integer value	USD	GBP	EUR	CAD
`100`	$1.00	£1.00	€1.00	CA$1.00
`1000`	$10.00	£10.00	€10.00	CA$10.00
`50000`	$500.00	£500.00	€500.00	CA$500.00
`1000000`	$10,000.00	£10,000.00	€10,000.00	CA$10,000.00

🚧
Exception: TransactionsViewResponse.amount, TransactionsViewResponse.merchantAmount, FeesViewResponse.amount, and FeesViewResponse.merchantAmount are strings, unlike every other monetary field in this API. Check actual values in your environment to confirm the format before applying arithmetic to these fields. See Transactions & Fees.

State codes: US and non-US

Field: CardholderCreate.state / CardholderUpdate.state

US residents: pass the 2-letter USPS state abbreviation (e.g. CA, NY, TX).
Non-US residents where state is not applicable: pass XX.
Non-US residents where an equivalent exists (province, canton, county): pass the relevant local abbreviation up to 50 characters.

ZIP / postal codes

Field: CardholderCreate.zipCode / CardholderUpdate.zipCode

US residents: 5-digit USPS ZIP code (e.g. 94105, 10001).
Non-US residents where postal code is not applicable: pass 00000.
Non-US residents with a postal code: pass the local code, up to 12 characters.