/

15 minute read

July 22, 2020

Accepted Countries

Use the /acceptedcountries endpoint to manage the countries where you authorize your cardholders to transact.

The /acceptedcountries endpoint is subject to role-based access control. Only users with the Admin role can create or update a list of accepted countries. Users with the Read role can retrieve lists of accepted countries.

Create a list of accepted countries

Action: POST
Endpoint: /acceptedcountries

Create an acceptedcountries object. Each acceptedcountries object contains a country_codes array, which is a comma-separated list of ISO 3166 three-digit numeric country codes. The ISO maintains the full list of country codes.

You can create as many acceptedcountries objects as you find necessary to support your various card products. Each card product uses a single acceptedcountries object, referenced by token in the accepted_countries_token field of the config.transaction_controls object. See The config.transaction_controls object for more information.

Your acceptedcountries object can serve as a limiting list of countries where transactions for your cardholders are allowed (is_whitelist = true), or it can serve as a limiting list of countries where transactions for your cardholders are prohibited (is_whitelist = false).

For example, to allow transactions in France, Italy, Germany, and Spain only, set is_whitelist to true and include codes 250, 380, 276, and 724 in your country_codes array.

To prohibit transactions in Belarus, Cuba, and North Korea only, set is_whitelist to false and include codes 112, 192, and 408 in your country_codes array.

Body field details

Fields Description

token

string
Optional

The unique identifier of the acceptedcountries object.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

name

string
Required

The name of the acceptedcountries object.

Allowable Values:

99 char max

is_whitelist

boolean
Required

Specifies if the list of accepted countries in this object is a whitelist. If set to true, then transactions are accepted for all countries included in the object’s country_codes array. If set to false, transactions are prohibited for all countries included in the object’s country_codes array.

Allowable Values:

true, false

Default Value:
false

country_codes

array
Required

A comma-delimited list of accepted countries by country code.

Allowable Values:

ISO 3166 three-digit numeric codes. For example, the numeric code for the United States is 840.

The ISO maintains the full list of country codes.

created_time

datetime
Optional

The time when the acceptedcountries object was created.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Optional

The time when the acceptedcountries object was last updated.

Allowable Values:

Valid timestamp

Body field details (response)

Fields Description

token

string
Returned

The unique identifier of the acceptedcountries object.

Allowable Values:

36 char max

name

string
Returned

The name of the acceptedcountries object.

Allowable Values:

99 char max

is_whitelist

boolean
Returned

Specifies if the list of accepted countries in this object is a whitelist. If set to true, transactions are accepted for all countries included in the object’s country_codes array. If set to false, transactions are prohibited for all countries included in the object’s country_codes array.

Allowable Values:

true, false

country_codes

array
Returned

The list of accepted countries by country code.

Allowable Values:

ISO 3166 three-digit numeric codes. For example, the numeric code for the United States is 840.

The ISO maintains the full list of country codes.

created_time

datetime
Returned

The time when the acceptedcountries object was created.

Allowable Values:

valid timestamp

last_modified_time

datetime
Returned

The time when the acceptedcountries object was last updated.

Allowable Values:

Valid timestamp

Update a list of accepted countries

Action: PUT
Endpoint: /acceptedcountries/{token}

Update an existing acceptedcountries object.

Each acceptedcountries object contains a country_codes array, which is a comma-separated list of ISO 3166 three-digit numeric country codes. The ISO maintains the full list of country codes.

Each of your card products uses a single acceptedcountries object, referenced by token in the accepted_countries_token field of the config.transaction_controls object. See The config.transaction_controls object for more information.

Your acceptedcountries object can serve as a limiting list of countries where transactions for your cardholders are allowed (is_whitelist = true), or it can serve as a limiting list of countries where transactions for your cardholders are prohibited (is_whitelist = false).

For example, to allow transactions in France, Italy, Germany, and Spain only, set is_whitelist to true and include codes 250, 380, 276, and 724 in your country_codes array.

To prohibit transactions in Belarus, Cuba, and North Korea only, set is_whitelist to false and include codes 112, 192, and 408 in your country_codes array.

URL parameters

Fields Description

token

string
Required

The token of the acceptedcountries object you want to update.

Allowable Values:

36 char max

Body field details

Fields Description

name

string
Optional

The name of the acceptedcountries object.

Allowable Values:

99 char max

is_whitelist

boolean
Optional

Specifies if the list of accepted countries in this object is a whitelist. If set to true, transactions are accepted for all countries included in the object’s country_codes array. If set to false, transactions are prohibited for all countries included in the object’s country_codes array.

Allowable Values:

true, false

Default Value:
false

country_codes

string
Optional

The list of accepted countries by country code.

Allowable Values:

ISO 3166 three-digit numeric codes. For example, the numeric code for the United States is 840.

The ISO maintains the full list of country codes.

Body field details (response)

Fields Description

token

string
Returned

The unique identifier of the acceptedcountries object.

Allowable Values:

36 char max

name

string
Returned

The name of the acceptedcountries object.

Allowable Values:

99 char max

is_whitelist

boolean
Returned

Specifies if the list of accepted countries in this object is a whitelist. If set to true, transactions are accepted for all countries included in the object’s country_codes array. If set to false, transactions are prohibited for all countries included in the object’s country_codes array.

Allowable Values:

true, false

country_codes

array
Returned

A comma-delimited list of accepted countries by country code.

Allowable Values:

ISO 3166 three-digit numeric codes. For example, the numeric code for the United States is 840.

The ISO maintains the full list of country codes.

created_time

datetime
Returned

The time when the acceptedcountries object was created.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Returned

The time when the acceptedcountries object was last updated.

Allowable Values:

Valid timestamp

Retrieve all lists of accepted countries

Action: GET
Endpoint: /acceptedcountries

Retrieve a list of acceptedcountries objects.

Query parameters

Fields Description

count

integer
Required

The number of acceptedcountries objects to return.

Allowable Values:

Integer

Default Value:
5

start_index

integer
Required

The starting index point in the list of acceptedcountries objects.

Allowable Values:

Integer

Default Value:
0 (The first acceptedcountries object in your system.)

name

string
Optional

Query for the name of a specific acceptedcountries object.

Allowable Values:

String

whitelist

boolean
Optional

Query for the whitelist status of the acceptedcountries objects.

Allowable Values:

true, false

search_type

string
Optional

Specifies the type of search you want to perform.

Allowable Values:

String

fields

string
Optional

A comma-delimited list of fields to return. Leave this parameter blank to return all fields in the acceptedcountries object.

Allowable Values:

token, name, is_whitelist, country_codes, created_time, last_modified_time

sort_by

string
Optional

Specify the sorting order of the returned list of acceptedcountries objects.

Allowable Values:

String

Default Value:
-lastModifiedTime

Body field details (response)

Fields Description

token

string
Returned

The unique identifier of the acceptedcountries object.

Allowable Values:

36 char max

name

string
Conditionally returned

The name of the acceptedcountries object. This field is returned when included in your query.

Allowable Values:

99 char max

is_whitelist

boolean
Conditionally returned

Specifies if the list of accepted countries in this object is a whitelist. If set to true, transactions are accepted for all countries included in the object’s country_codes array. If set to false, transactions are prohibited for all countries included in the object’s country_codes array.

This field is returned when included in your query.

Allowable Values:

true, false

country_codes

array
Conditionally returned

A comma-delimited list of accepted countries by country code. This field is returned when included in your query.

Allowable Values:

ISO 3166 three-digit numeric codes. For example, the numeric code for the United States is 840.

The ISO maintains the full list of country codes.

created_time

datetime
Conditionally returned

The time when the acceptedcountries object was created. This field is returned when included in your query.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Conditionally returned

The time when the acceptedcountries object was last updated. This field is returned when included in your query.

Allowable Values:

Valid timestamp

Retrieve a specific list of accepted countries

Action: GET
Endpoint: /acceptedcountries/{token}

Retrieve a specific acceptedcountries object. Send a GET request to the /acceptedcountries endpoint to retrieve existing acceptedcountries object tokens.

Query parameters

Fields Description

token

string
Returned

The unique identifier of the acceptedcountries object.

Allowable Values:

36 char max

fields

string
Optional

A comma-delimited list of fields to return. Leave this parameter blank to return all fields in the acceptedcountries object.

Allowable Values:

token, name, is_whitelist, country_codes, created_time, last_modified_time

Body field details (response)

Fields Description

token

string
Returned

The unique identifier of the acceptedcountries object.

Allowable Values:

36 char max

name

string
Conditionally returned

The name of the acceptedcountries object. This field is returned when included in your query.

Allowable Values:

99 char max

is_whitelist

boolean
Conditionally returned

Specifies if the list of accepted countries in this object is a whitelist. If set to true, transactions are accepted for all countries included in the object’s country_codes array. If set to false, transactions are prohibited for all countries included in the object’s country_codes array.

This field is returned when included in your query.

Allowable Values:

true, false

country_codes

string
Conditionally returned

A comma-delimited list of accepted countries by country code. This field is returned when included in your query.

Allowable Values:

ISO 3166 three-digit numeric codes. For example, the numeric code for the United States is 840.

The ISO maintains the full list of country codes.

created_time

datetime
Conditionally returned

The time when the acceptedcountries object was created. This field is returned when included in your query.

Allowable Values:

Valid timestamp

last_modified_time

datetime
Conditionally returned

The time when the acceptedcountries object was last updated. This field is returned when included in your query.

Allowable Values:

Valid timestamp

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.