Create a new user
Creating a new user means adding your customer's details to Wise, and then making a profile for them with which they can authorise transfers and access their balance. These steps are a quick guide to support the implementation of Hosted KYC.
To create a new user:
- Retrieve your client credentials token by calling the Retrieve Client Credentials endpoint.
- Create a user for your customer using Create User endpoint.
- Retrieve access tokens for the user by using Retrieve User Tokens endpoint.
- Create a personal profile for the user by using Create Personal Profile endpoint. If you are onboarding a business, this personal profile would be the Business Representative.
- If you are onboarding a business, create a business profile by using Create Business Profile endpoint.
- If you are onboarding a business, you may optionally add:
- Business directors Create business directors
- Ultimate beneficial owners (UBOs) of the business Create UBOs
POST /oauth/token
Obtain access_token based on your API client credentials.
Use Basic Authentication with your api-client-id/api-client-secret as the username/password. The body of the request must be sent as x-www-form-urlencoded.
"client_credentials"
Response
Returns a client credentials token object
curl https://api.sandbox.transferwise.tech/oauth/token \-u '<client id>:<client secret>' \-d 'grant_type=client_credentials'
POST /v1/user/signup/registration_code
Wise uses email address as unique identifier for users. If email is new (there is no active user already) then new user will be created.
When you are submitting an email which already exists amongst our users then you will get a warning that "You’re already a member. Please login". If user already exists then you need to redirect to "Get user authorization" webpage.
New user's email address
Randomly generated registration code that is unique to this user and request. At least 32 characters long. You need to store registration code to obtain access token on behalf of this newly created user in next step. Please apply the same security standards to handling registration code as if it was a password.
User default language for UI and email communication. Allowed values EN, US, PT, ES, FR, DE, IT, JA, RU, PL, HU, TR, RO, NL, HK. Default value EN.
Response
userId
User full name. Empty.
Customer email
true
User details. Empty.
curl -X POST https://api.sandbox.transferwise.tech/v1/user/signup/registration_code \-H 'Authorization: Bearer <client credentials token>' \-H 'Content-Type: application/json' \-d '{"email": "user@email.com","registrationCode": <unique guid for the user>,"language": "EN"}'
{"id": 12345,"name": null,"email": "new.user@domain.com","active": true,"details": null}
{"errors": [{"code": "NOT_UNIQUE","message": "You’re already a member. Please login","path": "email","arguments": ["email","class com.transferwise.fx.api.ApiRegisterCommand","existing.user@domain.com"]}]}
POST /oauth/token
You can now use registration code to obtain user access token and refresh token.
"registration_code"
New user's email address
Your API client_id
registrationCode from step 2
Response
Returns a user tokens object
curl https://api.sandbox.transferwise.tech/oauth/token \-u '<client id>:<client secret>' \-d 'grant_type=registration_code' \-d 'client_id=<client id>' \-d 'email=<user email>' \-d 'registration_code=<registration code used to create user>'
{"error": "invalid_grant","error_description": "Invalid user credentials."}
POST /v2/profiles/personal-profile
If a customer you are creating a profile for has first or last names that exceed 30 characters (e.g. they have many middle names) then you should truncate the names at length 30 characters and submit that value.
Occupations is required for CA, IN, JP, ID, IL, MX and within the US for the state NM.
Contact Details are used only for mandatory customer notifications and to help identify your customer if you contact Wise's Customer Support team.
First name (including middle names). Required
Last name. Required
Preferred first name, if different to the legal first name.
First name in Katakana. Required for from-JPY personal transfers
Last name in Katakana. Required for from-JPY personal transfers
First line of address. Required
City. Required
3 Letter country code (lower case). Required
Postal code
State code. Required for US, CA, BR and AU addresses
3 Letter country code (lower case)
Date of birth. Required
An external reference identifier mapping the customer of this profile to your system.
Contact email address. Please speak with your integration account manager for details on how customer communication is handled for your integration. Required
Contact phone number in international phone number format, example: "+1408XXXXXXX". Please speak with your integration account manager for details on how customer communication is handled for your integration. Required
Occupation field code - this field accepts any job or occupation that the customer does, as the only occupation format currently accepted is "FREE_FORM"
.
Occupation field format - the format of the occupation code being submitted. As of now, it only accepts the value "FREE_FORM"
.
curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/personal-profile \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-H 'X-idempotence-uuid: 054064c9-e01e-49fb-8fd9-b0990b9442f4' \-d '{"firstName": "Oliver","lastName": "Wilson","preferredName": "Olivia","firstNameInKana": null,"lastNameInKana": null,"address": {"addressFirstLine": "50 Sunflower Ave","city": "Phoenix","countryIso3Code": "usa","postCode": "10025","stateCode": "AZ"},"nationality": "usa","dateOfBirth": "1977-07-01","externalCustomerId": "12345-oliver-wilson","contactDetails": {"email": "o.wilson@example.com","phoneNumber": "+3725064992"},"occupations": [{"code": "Software Engineer","format": "FREE_FORM"}]}'
{"id": 30000001,"type": "personal","details": {"firstName": "Oliver","lastName": "Wilson","preferredName": "Olivia","address": {"addressFirstLine": "50 Sunflower Ave","city": "Phoenix","countryIso3Code": "usa","postCode": "10025","stateCode": "AZ"},"nationality": "usa","dateOfBirth": "1977-07-01","externalCustomerId": "12345-oliver-wilson","contactDetails": {"email": "o.wilson@example.com","phoneNumber": "+3725064992"},"occupations": [{"code": "Software Engineer","format": "FREE_FORM"}],"localizedInformation": []}}
POST /v3/profiles/business-profile
(beta)
Create a business profile and its authorized representative in a single request.
Business name
Business name in Katakana (only for Japanese businesses)
Business free form description. *Required if companyType is OTHER. If this is not provided for an OTHER companyType, the profile should not be allowed to create a transfer. For the rest of the companyType(s), it is highly recommended to always provide the business' description, to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.
Business registration number
Australian Company Number (only for Australian businesses)
Australian Business Number (only for Australian businesses)
Australian Registered Body Number (only for Australian businesses)
Company legal form. Allowed values:
- LIMITED
- PARTNERSHIP
- SOLE_TRADER
- LIMITED_BY_GUARANTEE
- LIMITED_LIABILITY_COMPANY
- FOR_PROFIT_CORPORATION
- NON_PROFIT_CORPORATION
- LIMITED_PARTNERSHIP
- LIMITED_LIABILITY_PARTNERSHIP
- GENERAL_PARTNERSHIP
- SOLE_PROPRIETORSHIP
- PRIVATE_LIMITED_COMPANY
- PUBLIC_LIMITED_COMPANY
- TRUST
- OTHER
Role of person. Allowed Values:
- OWNER
- DIRECTOR
- OTHER
First line of address
City
2 letter country code.
3 Letter country code. Must be lowercase
Postal code
State code
An external reference identifier mapping the customer of this profile to your system.
Email of the actor
Category of the business
Secondary category of the business
List of operational addresses
First line of address
City
2 letter country code
3 Letter country code. Must be lowercase
Postal code
State code
Business webpage. *Required if companyType is OTHER. If this is not provided for an OTHER companyType, the profile should not be allowed to create a transfer. For the rest of the companyTypes, it is highly recommended to always provide the business' website,to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.
ID of a Business Representative. This can be obtained from a previous call to create a business profile, in which case the same bBusiness Representative is linked to the current business effectively sharing it across multiple businesses. When the Business Representative ID is provided in this way it is the only field required for the Business Representative and none of the other fields should be provided.
First name of the person representating the business (including middle names). Required (unless Business Representative ID is provided)
Last name of the person representating the business. Required (unless Business Representative ID is provided)
Preferred first name of the person representing the business, if different to the legal first name.
First line of address of the person representing the business. Required (unless Business Representative ID is provided)
City of the person representing the business. Required (unless Business Representative ID is provided)
3 Letter country code (lower case) of the person representing the business. Required (unless Business Representative ID is provided)
Postal code of the person representing the business
State code of the person representing the business. Required for US, CA, BR and AU addresses (unless Business Representative ID is provided)
Contact email address of the person representing the business. Please speak with your integration account manager for details on how customer communication is handled for your integration. Required (unless Business Representative ID is provided)
Contact phone number in international phone number format, example: "+1408XXXXXXX" of the person representing the business. Please speak with your integration account manager for details on how customer communication is handled for your integration. Required (unless Business Representative ID is provided)
Date of birth of the person representing the business. Required (unless Business Representative ID is provided)
Business Category
Ensure when submitting a business profile that you submit a category and associated sub-category from the list below. You should map from the information you have about the business to one of our categories and sub-categories. If this is problematic please get in touch with us to discuss alternate solutions.
The categories and their sub-categories are as follows:
- CHARITY_NON_PROFIT
- CHARITY_ALL_ACTIVITIES
- CONSULTING_IT_BUSINESS_SERVICES
- ADVERTISING_AND_MARKETING
- ARCHITECTURE
- COMPANY_ESTABLISHMENT_FORMATION_SERVICES
- DESIGN
- FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
- IT_DEVELOPMENT
- IT_HOSTING_SERVICES
- IT_CONSULTING_AND_SERVICES
- LEGAL_SERVICES
- MANAGEMENT_CONSULTING
- SCIENTIFIC_AND_TECHNICAL_CONSULTING
- SOFTWARE_AS_A_SERVICE
- TRANSLATION_AND_LANGUAGE_SERVICES
- CONSULTING_OTHER
- SERVICES_OTHER
- FREELANCE_PLATFORMS
- RECRUITMENT_SERVICES
- MAINTENANCE_SERVICES
- FREELANCE_PLATFORMS
- DESIGN_MARKETING_COMMUNICATIONS
- ADVERTISING_AND_MARKETING
- ARCHITECTURE
- AUDIO_AND_VIDEO
- DESIGN
- PHOTOGRAPHY
- PRINT_AND_ONLINE_MEDIA
- TELECOMMUNICATIONS_SERVICES
- TRANSLATION_AND_LANGUAGE_SERVICES
- MEDIA_COMMUNICATION_ENTERTAINMENT
- ADULT_CONTENT
- AUDIO_AND_VIDEO
- FINE_ARTS
- ARTS_OTHER
- EVENTS_AND_ENTERTAINMENT
- GAMBLING_BETTING_AND_ONLINE_GAMING
- NEWSPAPERS_MAGAZINES_AND_BOOKS
- PERFORMING_ARTS
- PHOTOGRAPHY
- TELECOMMUNICATIONS_SERVICES
- VIDEO_GAMING
- EDUCATION_LEARNING
- SCHOOLS_AND_UNIVERSITIES,
- TEACHING_AND_TUTORING
- ONLINE_LEARNING
- FINANCIAL_SERVICES_PRODUCTS_HOLDING_COMPANIES
- CROWDFUNDING
- CRYPTOCURRENCY_FINANCIAL_SERVICES
- FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
- HOLDING_COMPANIES
- INSURANCE
- INVESTMENTS
- MONEY_SERVICE_BUSINESSES
- FINANCIAL_SERVICES_OTHER
- FOOD_BEVERAGES_TOBACCO
- ALCOHOL
- FOOD_MANUFACTURING_RETAIL
- RESTAURANTS_AND_CATERING
- SOFT_DRINKS
- TOBACCO
- VITAMINS_AND_DIETARY_SUPPLEMENTS
- HEALTH_PHARMACEUTICALS_PERSONAL_CARE
- HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES
- DENTAL_SERVICES
- DOCTORS_AND_MEDICAL_SERVICES
- ELDERLY_OR_OTHER_CARE_HOME
- FITNESS_SPORTS_SERVICES
- MEDICAL_EQUIPMENT
- NURSING_AND_OTHER_CARE_SERVICES
- PHARMACEUTICALS
- PHARMACY
- VITAMINS_AND_DIETARY_SUPPLEMENTS
- PUBLIC_GOVERNMENT_SERVICES
- PUBLIC_ALL_SERVICES
- MAINTENANCE_SERVICES
- GOVERNMENT_SERVICES
- TELECOMMUNICATIONS_SERVICES
- UTILITY_SERVICES
- REAL_ESTATE_CONSTRUCTION
- ARCHITECTURE
- CONSTRUCTION
- REAL_ESTATE_DEVELOPMENT
- REAL_ESTATE_SALE_PURCHASE_AND_MANAGEMENT
- RETAIL_WHOLESALE_MANUFACTURING
- AGRICULTURE_SEEDS_PLANTS
- FINE_ARTS
- ARTS_OTHER
- AUTOMOTIVE_SALES_SPARE_PARTS_TRADE
- AUTOMOTIVE_MANUFACTURING
- CHEMICALS
- CLOTHING
- ELECTRICAL_PRODUCTS
- FIREARMS_WEAPONS_AND_MILITARY_GOODS_SERVICES
- HOME_ACCESSORIES_FURNITURE
- FINE_JEWELLERY_WATCHES
- FASHION_JEWELLERY
- HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES
- LEGAL_HIGHS_AND_RELATED_ACCESSORIES
- MACHINERY
- PETS
- PRECIOUS_STONES_DIAMONDS_AND_METALS
- SPORTING_EQUIPMENT
- MANUFACTURING_OTHER
- RETAIL_WHOLESALE_MARKETPLACE_AUCTION
- RETAIL_WHOLESALE_OTHER
- TOYS_AND_GAMES
- TRAVEL_TRANSPORT_TOUR_AGENCIES
- ACCOMMODATION_HOTELS
- PASSENGER_TRANSPORT
- FREIGHT_TRANSPORT
- RIDESHARING_TRANSPORT_SHARING_SERVICES
- TRANSPORT
- TRAVEL_AGENCIES
- TOUR_OPERATORS
- TRAVEL_OR_TOUR_ACTIVITIES_OTHER
- OTHER
- OTHER_NOT_LISTED_ABOVE
curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/business-profile \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-H 'X-idempotence-uuid: 054064c9-e01e-49fb-8fd9-b0990b9442f4' \-d '{"businessName": "ABC Logistics Ltd","businessNameInKatakana": null,"businessFreeFormDescription": "Biz free form desc","registrationNumber": "12144939","acn": null,"abn": null,"arbn": null,"companyType": "LIMITED","companyRole": "OWNER","address": {"addressFirstLine": "1 A road","city": "London","countryIso2Code": "gb","countryIso3Code": "gbr","postCode": "11111"},"externalCustomerId": "67890-biz-acct","actorEmail": "biz-acct@abcl.com","firstLevelCategory": "CONSULTING_IT_BUSINESS_SERVICES","secondLevelCategory": "DESIGN","operationalAddresses": [{"addressFirstLine": "1 A road","city": "London","countryIso2Code": "gb","countryIso3Code": "gbr","postCode": "11111"}],"webpage": "https://abc-logistics.com","businessRepresentative": {"firstName": "Oliver","lastName": "Wilson","preferredName": "Olivia","address": {"addressFirstLine": "50 Sunflower Ave","city": "Phoenix","countryIso3Code": "usa","postCode": "10025","stateCode": "AZ"},"dateOfBirth": "1977-07-01","contactDetails": {"email": "o.wilson@example.com","phoneNumber": "+3725064992"}}}'
curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/business-profile \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-H 'X-idempotence-uuid: 054064c9-e01e-49fb-8fd9-b0990b9442f4' \-d '{"businessName": "ABC Logistics Ltd","businessNameInKatakana": null,"businessFreeFormDescription": "Biz free form desc","registrationNumber": "12144939","acn": null,"abn": null,"arbn": null,"companyType": "LIMITED","companyRole": "OWNER","address": {"addressFirstLine": "1 A road","city": "London","countryIso2Code": "gb","countryIso3Code": "gbr","postCode": "11111"},"externalCustomerId": "67890-biz-acct","actorEmail": "biz-acct@abcl.com","firstLevelCategory": "CONSULTING_IT_BUSINESS_SERVICES","secondLevelCategory": "DESIGN","operationalAddresses": [{"addressFirstLine": "1 A road","city": "London","countryIso2Code": "gb","countryIso3Code": "gbr","postCode": "11111"}],"webpage": "https://abc-logistics.com","businessRepresentative": {"businessRepresentativeId": 123}}'
POST /v1/profiles/{{business-profile-id}}/directors
Adds new directors to the business profile.
Returns the list of all directors associated with the business profile.
ID of the director. Automatically set.
Director first name
Director last name
Date of birth
3 character country code
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/directors \-H "Authorization: Bearer <your api token>" \-H "Content-Type: application/json" \-d '[{"firstName": "John","lastName": "Doe","dateOfBirth": "1982-05-20","countryOfResidenceIso3Code": "usa"},{"firstName": "Jane","lastName": "Doe","dateOfBirth": "1981-12-07","countryOfResidenceIso3Code": "usa"}]'
POST /v1/profiles/{{business-profile-id}}/ubos
Adds new ultimate beneficial owners to the business profile. Returns the list of all ultimate beneficial owners associated with the business profile.
Note that in some cases, we do not require the ownershipPercentage
. In these cases, null
should be passed as the value.
Owner full name
Date of birth
3 character country code
First line of address
Address post code
Percentage of ownership
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/ubos \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '[{"name": "John Doe","dateOfBirth": "1982-05-20","countryOfResidenceIso3Code": "usa","addressFirstLine": "123 Fake St","postCode": "FK 12345","ownershipPercentage": 30}]'
[{"id": "013ab1c2688d0185b582ee7e0bcb28b2","name": "John Doe","dateOfBirth": "1982-05-20","countryOfResidenceIso3Code": "usa","addressFirstLine": "123 Fake St","postCode": "FK 12345","ownershipPercentage": 30}]