Requirements for store details

Copy for LLMView as Markdown

When you onboard a connected account for Airwallex Payments through Native API, you must supply store details using the account_details.store_details object. This object describes the merchant’s selling activity: how they accept payment (operating models), what they sell, expected volumes, websites or physical locations, and related risk signals. You can submit it when you create an account API or update it via update an account API (before activation) or the account amendment API flow after activation.

Learn about the supported fields for store details, whether it is required or conditional, and how each field is used. You can also learn about error codes returned on failed validation and how to troubleshoot these errors.

Store details reference

Field	Type	Required	Description
`store_details`	object	Required	Relevant information associated with the store you are applying payment solutions for.
`store_details.operating_models`	`array`	Required	The channel shoppers will use to pay for their orders. One or more of `ONLINE_CHECKOUT`, `INVOICES_OR_CUSTOM_ORDER_LINKS`, `IN_PERSON`. See supported operating models for details.
`store_details.store_name`	`string`	Required	The trading name your store is operating as. This name will also appear on the receipts to your customers. Max length is 64 characters.
`store_details.store_websites`	`array`	Required if operating models include `ONLINE_CHECKOUT`; otherwise optional	All websites associated with the store you are applying payment solutions for. They must be in the same industry selling the same or similar goods and services, otherwise you will need to submit another application as a different store.
`store_details.store_websites.url`	`string`	Required if operating models include `ONLINE_CHECKOUT`; otherwise optional	URL of the store websites, including online store, marketplace stores, app-store links or other relevant websites.
`store_details.store_description`	`string`	Required	Free text description of your store's goods or services offerings. Max length is 500 characters.
`store_details.industry_code`	`string`	Required	The code of the industry category most aligned with your store. See Industry categories API to retrieve a list of categories.
`store_details.store_address`	`object`	Required if operating models include `IN_PERSON`; otherwise optional	Physical address of the store.
`store_details.store_address.address_line1`	`string`	Required if operating models include `IN_PERSON`; otherwise optional	The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.
`store_details.store_address.address_line2`	`string`	Optional	An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.
`store_details.store_address.country_code`	`string`	Required if operating models include `IN_PERSON`; otherwise optional	Country code (2-letter ISO 3166-2 country code)
`store_details.store_address.postcode`	`string`	Conditional	Postcode or zip code. Only applicable if relevant to selected country.
`store_details.store_address.state`	`string`	Conditional	Name of state. Only applicable if relevant to selected country.
`store_details.store_address.suburb`	`string`	Required if operating models include `IN_PERSON`; otherwise optional	Name of city/suburb.
`store_details.estimated_transaction_volume`	`object`	Required	Your store's anticipated volume of transactions in the next 12 months with Airwallex.
`store_details.estimated_transaction_volume.currency`	`string`	Required	Currency of the transaction volume (3-letter ISO 4217 currency code)
`store_details.estimated_transaction_volume.average_amount_per_transaction`	`string`	Required	The average transaction size of your store. Must be greater than 0 and less than or equal to `max_amount_per_transaction`.
`store_details.estimated_transaction_volume.max_amount_per_transaction`	`string`	Required	The maximum transaction size of your store. Must be greater than 0 and less than or equal to `monthly_transaction_amount`.
`store_details.estimated_transaction_volume.monthly_transaction_amount`	`string`	Required	The average monthly volume of your store. Must be greater than 0 and greater than or equal to `max_amount_per_transaction`.
`store_details.cross_border_transaction_percent`	`string`	Required	Percentage of products or services provided to international customers residing outside of where your business is registered.
`store_details.fulfillment_days`	`int`	Conditional	Number of days your customers will typically need to wait to receive their goods or services after paying for their orders.
`store_details.payment_distribution`	`array`	Required if the store has existing payment operations; otherwise optional	Anticipated transaction volume split by payment methods. Sum of distributions must be exactly 100.
`store_details.payment_distribution.payment_type`	`string`	Required if the store has existing payment operations; otherwise optional	Type of payment methods; one of `CARDS`, `BANK_DIRECT_DEBIT`, `OTHER`.
`store_details.payment_distribution.percentage`	`string`	Required if the store has existing payment operations; otherwise optional	Percentage of anticipated transaction volume.
`store_details.dispute_percent`	`string`	Required if the store has existing payment operations; otherwise optional	Average dispute rate (percentage of total successful payments that are claimed as disputed charges by card schemes) of your store in the past three months.
`store_details.refund_percent`	`string`	Required if the store has existing payment operations; otherwise optional	Average refund rate (percentage of total successful payments that are refunded to your customers) of your store in the past three months.
`store_details.mcc`	`string`	Optional	Current or desired MCC for your store.
`store_details.financial_statements`	`array`	Optional	Additional documents about your store's financials.
`store_details.financial_statements.file_id`	`string`	Optional	ID of file as provided in the response of the File Service API API.
`store_details.store_photos`	`array`	Optional	Store photos of the shopfront clearly displaying the company name or photo of building entrance as well as directory with company name listed.
`store_details.store_photos.file_id`	`string`	Required	All relevant store photos, if more than one physical store, provide one photo of each.
`store_details.employee_size`	`int`	Optional	Total number of staff in all stores.
`store_details.selling_to_country_code`	`array`	Optional	List of country codes where products are sold.
`store_details.shipping_from_country_codes`	`array`	Optional	List of country codes from which goods are shipped.

Sample payload

JSON

1{
2    "account_details": {
3        "store_details": {
4            "cross_border_transaction_percent": "50.0",
5            "dispute_percent": "0.5",
6            "estimated_transaction_volume": {
7                "average_amount_per_transaction": "10000.0",
8                "currency": "USD",
9                "max_amount_per_transaction": "20000.0",
10                "monthly_transaction_amount": "500000.0"
11            },
12            "financial_statements": [
13                {
14                    "file_id": "Yzc5YzlhZDctMjVjMC00MTc3LTkyODMtNDJhYjRjMzllN2JjLHwsaG9uZ2tvbmcsfCxpbWFnZSAoMTApLnBuZ18xNjk0NDA1MjE0MjM2"
15                }
16            ],
17            "fulfillment_days": 5,
18            "industry_code": "ICCV3_041501",
19            "mcc": "0763",
20            "operating_models": [
21                "ONLINE_CHECKOUT",
22                "INVOICES_OR_CUSTOM_ORDER_LINKS",
23                "IN_PERSON"
24            ],
25            "payment_distribution": [
26                {
27                    "payment_type": "CARDS",
28                    "percentage": "50.0"
29                },
30                {
31                    "payment_type": "BANK_DIRECT_DEBIT",
32                    "percentage": "50.0"
33                }
34            ],
35            "refund_percent": "5",
36            "store_address": {
37                "address_line1": "Stree nowhere, build 2",
38                "country_code": "AU",
39                "postcode": "12389",
40                "state": "NSW",
41                "suburb": "Sydney"
42            },
43            "store_description": "i sell toys",
44            "store_name": "my stores",
45            "store_websites": [
46                {
47                    "url": "https://www.airwallex.com"
48                }
49            ]
50        },
51        "business_person_details": [
52            ...more fields
53        ],
54        "business_details": {
55      ...more fields
56         },
57        "legal_entity_type": "BUSINESS"
58    },
59    "customer_agreements": {
60        "agreed_to_data_usage": true,
61        "agreed_to_terms_and_conditions": true,
62        "opt_in_for_marketing": true
63    },
64    "primary_contact": {
65        "email": "[email protected]"
66    }
67}
68

Troubleshooting validation errors

When account_details.store_details fails validation, the API returns HTTP 400 Bad Request with a structured body. Parse details.errors object to surface validation issues to the user. Note that multiple errors can appear in one response.

Error response format

JSON

1{
2  "code": "validation_failed",
3  "message": "store_details validation failed",
4  "source": "account_details.store_details",
5  "details": {
6    "errors": [
7      {
8        "code": "INDUSTRY_CODE_INVALID_FORMAT",
9        "message": "Industry code must be in format ICCV3_XXXXXX where X can be digits or 'X' (e.g., ICCV3_000301, ICCV3_0800XX)"
10      },
11      {
12        "code": "STORE_PHOTOS_REQUIRED_FOR_IN_PERSON",
13        "message": "Store photos are required when operating model includes IN_PERSON"
14      }
15    ]
16  }
17}

Validation errors reference

The table below lists validation error codes and messages you may get when account_details.store_details is invalid, along with suggested next steps.

Field	Error code	Error message	Next steps
`store_name`	`STORE_NAME_REQUIRED`	Store name is required.	Provide a store name.
	`STORE_NAME_TOO_LONG`	Store name cannot exceed 64 characters.	Ensure store name is less than 64 characters.
	`STORE_NAME_INVALID_CHARACTERS`	Store name should only contain allowed latin characters, `^[A-Za-z0-9,.:/+-~·[]&()#\\s]*$`	Remove unsupported characters from the store name.
`operating_models`	`OPERATING_MODELS_REQUIRED`	Operating models is required.	Provide at least one operating model, `ONLINE_CHECKOUT`, `INVOICES_OR_CUSTOM_ORDER_LINKS`, `IN_PERSON`.
`operating_models`	`OPERATING_MODELS_INVALID`	Invalid operating model provided.	Provide a supported value.
`store_description`	`STORE_DESCRIPTION_REQUIRED`	Store description is required.	Provide a store description.
`store_description`	`STORE_DESCRIPTION_TOO_LONG`	Store description cannot exceed 500 characters.	Ensure store description is less than 500 characters.
`industry_code`	`INDUSTRY_CODE_REQUIRED`	Industry code is required.	Provide an industry code in the required format.
`industry_code`	`INDUSTRY_CODE_INVALID_FORMAT`	Industry code must be in format ICCV3_XXXXXX where X can be digits or 'X', for example, ICCV3_000301, ICCV3_0800XX.	Ensure industry code meets the format requirements.
`mcc`	`MCC_INVALID_FORMAT`	MCC must be 4 digits.	Use exactly 4 digits for MCC.
`estimated_transaction_volume`	`ESTIMATED_TRANSACTION_VOLUME_REQUIRED`	Estimated transaction volume is required.	Ensure transaction volume details are provided.
`estimated_transaction_volume.currency`	`TRANSACTION_VOLUME_CURRENCY_REQUIRED`	Transaction volume currency is required.	Ensure transaction volume currency details are provided.
`estimated_transaction_volume.average_amount_per_transaction`	`TRANSACTION_VOLUME_AVERAGE_AMOUNT_REQUIRED`	Average amount per transaction is required.	Ensure average amount per transaction is provided.
`estimated_transaction_volume.max_amount_per_transaction`	`TRANSACTION_VOLUME_MAX_AMOUNT_REQUIRED`	Maximum amount per transaction is required.	Ensure maximum amount per transaction is provided.
`estimated_transaction_volume.max_amount_per_transaction`	`TRANSACTION_AMOUNTS_ILLOGICAL`	Maximum amount per transaction must be greater than or equal to average amount.	Ensure maximum amount is greater than or equal to the average amount.
`estimated_transaction_volume.monthly_transaction_amount`	`TRANSACTION_VOLUME_MONTHLY_AMOUNT_REQUIRED`	Monthly transaction amount is required.	Ensure monthly transaction amount is provided.
`estimated_transaction_volume.monthly_transaction_amount`	`TRANSACTION_AMOUNTS_MONTHLY_TOO_LOW`	Monthly transaction amount must be greater than or equal to maximum amount per transaction.	Ensure monthly transaction amount is greater than or equal to the maximum amount per transaction.
`cross_border_transaction_percent`	`CROSS_BORDER_TRANSACTION_PERCENT_REQUIRED`	Cross border transaction percent is required.	Ensure cross border transaction percent is provided.
`cross_border_transaction_percent` `dispute_percent` `refund_percent`	`PERCENTAGE_OUT_OF_RANGE`	Percentage must be between 0 and 100.	Ensure percentage value is between zero and 100.
`payment_distribution`	`PAYMENT_DISTRIBUTION_INVALID_SUM`	Payment distribution percentages must sum to 100%.	Ensure payment distribution percentages sum to 100%.
`store_websites`	`STORE_WEBSITES_REQUIRED_FOR_ONLINE_CHECKOUT`	Store websites are required when operating models include `ONLINE_CHECKOUT`.	Provide at least one website URL in the correct format.
`store_websites[].url`	`WEBSITE_URL_INVALID_FORMAT`	Website URL must start with `http://` or `https://`.	Ensure website URL starts with `http://` or `https://`.
`store_address`	`STORE_ADDRESS_REQUIRED_FOR_IN_PERSON`	Store address is required when operating model includes `IN_PERSON`.	Provide at least one store address.
`store_address[i].country_code`	`STORE_ADDRESS_COUNTRY_CODE_REQUIRED_FOR_IN_PERSON`	Country code is required for store address when operating model includes IN_PERSON.	Provide country code for each address.
`store_address[i].address_line1`	`STORE_ADDRESS_LINE1_REQUIRED_FOR_IN_PERSON`	Address line 1 (street address) is required for store address when operating model includes IN_PERSON.	Provide street address for the store.
`store_address[i].suburb`	`STORE_ADDRESS_SUBURB_REQUIRED_FOR_IN_PERSON`	Suburb is required for store address when operating model includes IN_PERSON.	Provide suburb for the store address.
`store_photos`	`STORE_PHOTOS_REQUIRED_FOR_IN_PERSON`	Store photos are required when operating model includes IN_PERSON.	Provide at least one store photo.
`fulfillment_days`	`FULFILLMENT_DAYS_OUT_OF_RANGE`	Fulfillment days must be between 1 and 3650.	Provide a value between 1 and 3650.
`employee_size`	`EMPLOYEE_SIZE_INVALID`	Employee size must be at least 1.	Provide a value greater than or equal to 1.

Was this page helpful?