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
callingCodemust always be exactly 3 characters, zero-padded from the left. Pass001for the United States (not1),044for the United Kingdom (not44). Three-digit codes (e.g.971for the UAE,852for 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
countryCallingCode is not a dialing codeDespite 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, andFeesViewResponse.merchantAmountare 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.