Handle verification with tokens

Connect platforms can use Stripe.js, the API, or mobile client libraries to securely collect account details from their users.

Before we can enable charges and payouts for connected accounts, you must fulfil Know Your Customer (KYC) requirements. To do so, provide identity verification information about your accounts to Stripe, which we then verify. You can perform this task with Account Tokens and Person Tokens. Tokens ensure that personally identifiable information (PII) doesn’t touch your servers, so your integration can operate securely. These tokens also allow Stripe to more accurately detect potential fraud.

You can only use tokens for:

Legal entity details (information about the business or individual)
Person details
Indicating acceptance of the Stripe Connected Account Agreement

You can’t use tokens for any other account information, including:

Configuration settings on the account (for example, payout schedules)
Non-sensitive information on the account (for example, support url, support phone number)
The country of the connected account

You create tokens using Stripe.js, the API or one of the mobile client libraries. The process is effectively the same as tokenising payment details or external accounts. Your connected account’s information is sent directly to Stripe and exchanged for a token that you can use in create and update API calls.

Regional considerations France

French platforms must use account tokens, which are an alternative to the agent model for platform the related setting compliance. The key benefit of tokens for French platforms is that information is transferred from the user directly to Stripe. Not having to store PII data is still a benefit, but not necessarily a requirement. For platforms in other countries, account tokens are optional but recommended.

Create and use tokens

Tokens require both client-side and server-side code:

Create the HTML form that takes the user’s input.
Add JavaScript that sends the form data to Stripe, receives a token in return, and submits that token to your server.
Use the token in a server-side Stripe API call.

The following example shows how to use account tokens and person tokens. Both types are required when providing legal entity and person details for companies. If you onboard only individuals, you don’t need person tokens. Instead, create account tokens and pass the individual hash on the Account object to provide the required information.

Create an HTML form

The first step is to create an HTML form that collects the required information for the account and the person. This includes acceptance of the Stripe Connected Account Agreement.

Collect account and person details

Create form elements to collect the required information, such as name, address and anything else required by the user’s country.

form.html

<form class="my-form" action="/create-person" method="post">
 <input type="hidden" name="token-account" id="token-account">
 <input type="hidden" name="token-person" id="token-person">
 <label>
 <span>Business Name</span>
 <input class="inp-company-name">
 </label>
 <fieldset>
 <legend>Business Address</legend>
 <label>
 <span>Street Address Line 1</span>

Present the Stripe Connected Account Agreement

As the platform, you must make clear to your users that processing of payments is provided subject to the Stripe Connected Account Agreement. Indicating acceptance of the Stripe Connected Account Agreement is a requirement for using an account token to create a new connected account.

Note

Only platforms that can accept the service agreement through the API can create Account Tokens that specify tos_shown_and_accepted.

We recommend you include language like the following, including links to both our agreement and your terms of service.

Select a language

English

French

No results

Add JavaScript

Next, the page needs JavaScript that:

Interrupts the form submission.
Calls the stripe. createToken() method to request account and person tokens.
Sends the IDs of the received tokens to your server.

For simplicity, data validation and error handling are omitted in the following code, but remember to add both to your actual integration.

Provide two arguments to the stripe.createToken() method:

The value account or person , to specify the kind of token to create
A generic object of information

The JavaScript object provided as the second argument needs to parallel the structure of the Account or Person object you’re tokenising.

Account tokens require a top-level company or individual property, with an appropriate structure of child properties.
For person tokens, pass the Person object’s properties directly. (If you have existing code that wraps them in a person property, you don’t have to update it.)

To represent the user’s acceptance of the Stripe Connected Account Agreement, provide a top-level tos_shown_and_accepted property with a value of true (only account tokens are used for this).

You must still use tokens (to create or update a person) using server-side code. You can send the token ID to your server using whatever approach makes sense for your application (for example, an XHR request). For simplicity, this code example stores the token ID in a hidden form input and then submits the form.

script.js

// Assumes you've already included Stripe.js!
const stripe = Stripe('pk_test_GvF3BSyx8RSXMK5yAFhqEd3H');
const myForm = document.querySelector('.my-form');
myForm.addEventListener('submit', handleForm);

async function handleForm(event) {
 event.preventDefault();

 const accountResult = await stripe.createToken('account', {
 business_type: 'company',
 company: {
 name: document.querySelector('.inp-company-name').value,
 address: {
 line1: document.querySelector('.inp-company-street-address1').value,
 city: document.querySelector('.inp-company-city').value,
 state: document.querySelector('.inp-company-state').value,
 postal_code: document.querySelector('.inp-company-zip').value,
 },
 },
 tos_shown_and_accepted: true,
 });

 const personResult = await stripe.createToken('person', {
 first_name: document.querySelector('.inp-person-first-name').value,
 last_name: document.querySelector('.inp-person-last-name').value,
 address: {
 line1: document.querySelector('.inp-person-street-address1').value,
 city: document.querySelector('.inp-person-city').value,
 state: document.querySelector('.inp-person-state').value,
 postal_code: document.querySelector('.inp-person-zip').value,
 },
 });

 if (accountResult.token && personResult.token) {
 document.querySelector('#token-account').value = accountResult.token.id;
 document.querySelector('#token-person').value = personResult.token.id;
 myForm.submit();
 }
}

Upon successfully receiving the tokens from Stripe, the JavaScript stores the token IDs in a hidden form input and then submits the form (to your server). The final steps are for your server-side code to use the tokens to create an account and a person.

Create an account

Use the account token ID to create the account. The country and business type are provided outside the token.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

When creating an account token, setting tos_shown_and_accepted to true automatically populates the date, ip, and user_agent attributes of the Account object’s tos_acceptance attribute. If you create an account without using an account token, you must provide values for those attributes.

Make sure to note the account ID that’s returned so that you can use it to create Person objects for the account.

Create a person

Create a person by providing the ID of the person token as the value for the person_token parameter (you also need the account ID the person is for). You can use the requirements hash on the Account object to determine what information needs to be collected and from which persons.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Create account tokens with the mobile SDKs

You can also create an account token with our Android or iOS SDKs (mobile only supports account tokens). This is sufficient for creating an individual account, but you must use Stripe.js to create the person token that you need for a company account.

Select a language

Swift

Objective C

No results

import UIKit
import StripePayments

let companyParams = STPConnectAccountCompanyParams()
companyParams.name = company.name
companyParams.address = STPConnectAccountAddress()
companyParams.address.line1 = company.address_line_1
companyParams.address.city = company.address_city
companyParams.address.state = company.address_state
companyParams.address.country = company.address_country
companyParams.address.postalCode = company.address_postal_code

guard let accountParams = STPConnectAccountParams(tosShownAndAccepted: true, company: companyParams) else {
 // The TOS was not accepted
 return
}

STPAPIClient.shared.createToken(withConnectAccount: accountParams) { (accountToken, error) in
 if let error = error {
 // display an error to your user
 }
 else {
 // use account token to create a Connect account server-side
 }
}

Handle a file upload

When a connected account needs to provide Stripe with a scan of an identity document (for example, a passport), include the uploaded File ID in an account or person token, depending on where the verification requirement appears. The following account token example uploads an individual’s identity document as follows:

Interrupts the form submission.
If a file was uploaded, sends it to Stripe and receives a File ID in return.
Adds the File ID to the individual data for the account token request.
Calls the stripe. createToken() method to request an account token.
Sends the ID of the received account token to your server.

To begin, add a file element to the form. The uploaded file needs to be a colour image (smaller than 8,000 pixels by 8,000 pixels), in JPG, PNG, or PDF format and less than 10MB in size.

<input type="file" id="id-file" name="id-file" accept=".jpeg,.jpg,.png,.pdf">

Next, in your JavaScript that handles the form’s submission, send the uploaded file to Stripe. This needs to happen before creating the account token.

Finally, include the returned file ID as the verification.document.front value in the generic object provided to the createToken() call:

const result = await stripe.createToken('account', {
 business_type: 'individual',
 individual: {
 first_name: document.querySelector('.inp-first-name').value,
 last_name: document.querySelector('.inp-last-name').value,
 address: {
 line1: document.querySelector('.inp-street-address1').value,
 city: document.querySelector('.inp-city').value,
 state: document.querySelector('.inp-state').value,
 postal_code: document.querySelector('.inp-zip').value,
 },
 verification: {
 document: {
 front: fileData.id,
 },
 },
 },
 tos_shown_and_accepted: true,
});

Update legal entity and person details

You can use tokens to update an existing account’s legal entity and person information. Create the tokens you need using the same combination of HTML and JavaScript as above, and then perform an update Account or update Person call providing the new token ID.

You must create and provide a new token when updating legal entity details previously set using an account token.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

When using tokens for updates:

An existing value is replaced with a new value.
If no new value is provided, the existing value remains.
You can’t unset an existing value.
The tos _ shown _ and _ accepted parameter is ignored and can be omitted.
You can use an account or person token for an update whether or not a token was originally used when creating the account or person.
If the account or person was originally created using an account token, you can only update values using another token.

For example, if an account is created with a token containing only a name and date of birth, you’d create a subsequent token containing only the address information and then perform an update account call to add the address details to the account.

Remove legal entity and person details

To clear any legal entity or person details or to explicitly set a value as null, pass an empty string in an update Account or update Person call. Use an update call, not a token, even if you originally used a token. You can assign empty strings only to optional attributes (for example, the second line of an address). You can’t assign them to any required attributes.

Handle verification with tokens

Connect platforms can use Stripe.js, the API, or mobile client libraries to securely collect account details from their users.

Regional considerations France

Create and use tokens

Create an HTML form

Collect account and person details

Present the Stripe Connected Account Agreement

Note

Add JavaScript

Create an account

Create a person

Create account tokens with the mobile SDKs

Handle a file upload

Update legal entity and person details

Remove legal entity and person details

See also