The /file/upload API calls

The /file/upload API is a single endpoint that allows your application to upload documents on behalf of a merchant account for asynchronous risk and fraud review when WePay is unable to verify the merchant’s identity automatically.

Document uploads

While WePay makes every effort not to create friction for your users, if we cannot verify a user’s identity through any other means, we will require the user to provide us with documents that prove their identity. All partners must be prepared for the possibility that their users (merchants) must upload documents. WePay uses a risk-based approach in deciding when your users must upload documents. Documents may be requested after your users have started accepting transactions and/or settled funds to their bank accounts.

Reviewing documents

Once your user submits documents, the KYC state state changes from require_docs to in_review and the account state state changes from action_required to active because there is no further action required of the user. Documents are reviewed manually by WePay within two business days.

If WePay is unable to verify the user’s identity with the documents provided, the user will be required to upload additional documents. The KYC state will return to require_docs and the account state will return to action_required. WePay reserves the right to disable an account after multiple failed attempts at verifying users by examining their documents.

How to use this API

When your merchant’s KYC state changes to require_docs, your merchant should be notified that they must upload documents to finish account setup.

Your application will take the following steps to upload a document to WePay:

  1. Make a /file/upload call for each document that needs to be uploaded. Your application is returned a file_id for each uploaded document.
  2. Call /account/kyc/modify using the file IDs to confirm that the documents originated from a valid application. Unconfirmed documents are not reviewed and are deleted after 30 minutes.


Your application may upload documents anytime using /file/upload, but your application will not be able to call /account/kyc/modify unless the merchant’s KYC state is require_docs.

The file size limit is 10 MB. If your application attempts to upload a file in excess of 10 MB, a HTTP error code 413 is returned (request entity too large).

Version: v2 2017-02-01

POST Endpoint





The parameters in this API call are multipart/form-data parameters, not JSON parameters.


Parameter Required Type Description
file Yes File The document being uploaded on behalf of the merchant for WePay review. Possible file extensions: pdf, jpg, jpeg, png, or no extension.
type Yes Enum Possible values: passport, drivers_license, other_government_issued_photo_id, current_lease_contract, current_utility_bill, benefits_card, birth_certificate, certificate_of_citizenship, certificate_of_naturalization, certified_copy_of_court_order, employment_authorization_card, permanent_resident_card, social_security_card, social_insurance_number_card, evidence_of_corporate_registration, evidence_of_nonprofit_registration, evidence_of_authority, current_bank_statement, current_local_tax_bill, mortgage_statement, and electoral_register_entry.
account_id Yes Integer (64 bits) The associated merchant’s unique account ID.

Example (command line)

curl -X POST -H "Content-Type: multipart/form-data; \
-F "type=drivers_license" \
-F "account_id=747904422" \
-F "file=@foobar.jpg" \
"" \


Response Type Description
file_id Integer (64 bits) The unique ID of the uploaded document.


   "file_id": 12345