JavaScript Library

 

Access the Javascript libraries below:

There are no third-party dependencies for this library.

Initialize the Helper JS library on your platform's pages where you will tokenize information, and where WePay requires Risk headers:

Clear JS Injection LocationsClear Gated Options JS Injection Locations
  • Create Legal Entities
  • Create Payments
  • Create Refunds
  • Create Legal Entities
  • Update Legal Entities
  • Create Payout Methods
  • Create Accounts
  • Update Accounts
  • Create Payments
  • Create Refunds

Risk Headers

There are two Risk Headers: the Risk Token, and the Client-IP.

The Risk Token allows us to capture attributes about a payer or merchant's device, and have our algorithms identify any suspicious device pattern. If you use the Helper Javascript library for tokenization, then you don't need to explicitly call WePay.risk.get_risk_token() to capture a token, and send on API calls. If you are not tokenizing fields, then you will call that field, and send it to your server, where you will make calls to the WePay API.

In addition, Client-IP is a data point stored in the Risk Token. If you use the Helper JS library for tokenization, then this header will be created automatically along with the Risk Token. If you are not tokenizing, this header will be created automatically along with the Risk Header, but you must then pass the Client IP your server and add as its own header.

Tokenization

To help your platform avoid PCI compliance overhead, WePay provides a tokenization process that allows your application to send highly sensitive data directly to WePay, while giving your platform control over how that data is used.

In addition to reducing PCI compliance, you can use Tokens to collect personally identifiable information (PII), and not have to worry about processing or storing PII on your own systems.

You can add tokens for the following endpoints:

EndpointTokenizable Fields and Objects
legal_entities
  • additional_representatives
  • address
  • controller
  • country
  • custom_data
  • description
  • entity_country_info
  • entity_name
  • phone
  • primary_url
  • rbits
  • terms_of_service
payment_methods
  • credit_card
  • custom_data
  • payment_bank_us
  • rbits
  • type
payout_methods
  • custom_data
  • nickname
  • payout_bank_ca
  • payout_bank_uk
  • payout_bank_us
  • rbits
  • type

Tokenization occurs through the Javascript library. You will call the Javascript function, receive a token, and send a POST request to the above endpoints with the token in the body.

There are certain values that you won't be able to read in the Object's response. For example, if you don't tokenize the birthday field, and update a Legal Entity, it'll be stored, but every call to retrieve or update the resource will show the value true instead of the Birthday itself. This behavior only applies to Birthday and Social Security Number of Legal Entities.

If an Object already has a field value from a token, that same field can then be passed through a server API request so long as the new value matches the existing value exactly. If you did not store the value originally sent in the token, you may be able to retrieve it from the Object with a GET request. Otherwise, it is recommended to omit the field from the server request.

Tokenization Quickstart

  1. Configure the JavaScript library
  2. Create a token
  3. Use a token
  4. Tokenization Errors

This mini-guide will help you set up the Javascript library.

Configure the JavaScript library

In the <head> section of your webpage, include a script tag with the source set to the WePay Helper JavaScript library: https://cdn.wepay.com/wepay.min.js. This gives the library enough time to collect risk-related information.

Copy
Copied
<script src="https://cdn.wepay.com/wepay.min.js"></script>

Then, add your platform information to the WePay JavaScript library.

Copy
Copied
<script src="https://cdn.wepay.com/wepay.min.js"></script>
<script>
  var myAppId = "{your-app-id}";
  var apiVersion = "3.0";
  var error = WePay.configure("stage", myAppId, apiVersion);
  if (error) {
    // An error is returned if any fields are missing or invalid.
  console.log(error);
  }
</script>
Note

Function requirements: Two of the library functions have required parameters: WePay.configure and WePay.tokens.create. Find the specifics of those requirements below:

WePay.configure

Required ParameterDescription
environmentAn enumeration (expected values are stage or production) indicating the environment where the JavaScript will make requests.
app_idYour application's ID, which is used to manage ownership of tokens created by the JavaScript (found in the partner dashboard).
api-versionThe API Version being used for the calls running through the WePay Helper Javascript library.

WePay.tokens.create

Required ParameterDescription
bodyThe body of the tokenization request. Must be a JSON object with two fields:

Field 1 must include the key resource and the value should be the resource where you intend to pass tokenized data.
Field 2 must include the key name matching the value for resource in field 1. The value is the JSON data your platform wants to tokenize. You can tokenize any of the fields in a resource's schema. For example, your platform can tokenize any data it would normally send to the legal_entities or legal_entities/id endpoints when tokenizing for the legal entities resource.
headersAny additional headers to send to the WePay server with your tokenization request.
callbackA function called when the request is completed. If this field is not provided, the tokenization request will happen synchronously - blocking further JavaScript execution until the request finishes (not recommended). The single argument provided to the callback function will be a JSON response.

Example of the body parameter:
Copy
Copied
{
    "resource": "legal_entities",
    "legal_entities": {
        "country_info": {
            "US": {
                "social_security_number": "012-34-5678"
            }
        }
    }
}

Create a token

This example looks at tokenizing a Legal Entity.

Construct your request using information provided by your merchant.

Copy
Copied
<script>
  document.getElementById("submit-button").addEventListener('click', function() {
    WePay.tokens.create({
      "resource": "legal_entities",
      "legal_entities": {
        "controller": {
          "date_of_birth": {
            "year": 1975,
            "month": 1,
            "day": 1
          },
          "personal_country_info": {
            "US": {
              "social_security_number": "012-34-5678"
            }
          }
        }
      }
    }, {}, function(response) {
      // Handle the response by passing the token to your webserver
      // and using it in a POST /legal_entities request.
      console.log(response);
    });
  });
</script>

Tokens created through Javascript are validated against our API schema, so if you pass an incorrect format, the token will fail to create.


Use a token

Your platform's servers pass the token via an HTTP request. WePay takes token data, and combines it with other parameters provided in the HTTP request. Tokens have a time to live (TTL) of 30 minutes.

For example, using the token we created above for a legal entity, your platform server will make a request passing a token and the country parameter.

Copy
Copied
curl -X POST \
  https://stage-api.wepay.com/legal_entities \
  -H 'Api-Version: 3.0' \
  -H 'App-Id: app-12345' \
  -H 'App-Token: app-token-12345' \
  -H 'Content-Type: application/json' \
  -d '{
  "country": "US",
  "token": {
    "id": "legal_entities-91af0e49-000e-4684-a7b9-a2deba006971"
  }
}'
Note

Token Permissioned Fields: Since the token is created entirely on the web client, your platform's ability to guarantee what is in the token would normally be limited. However, for platforms that need control over what data was provided, you can provide the permissioned_fields list in the token structure in addition to the id.

Permissioned fields are a list of dot-notated JSON paths that are allowed to set by this token. In our previous example, we expect our client to modify the date_of_birth fields and the social_security_number fields of the controller structure. We can make sure that the token does not modify other fields by providing permissioned_fields with the server request:

Copy
Copied
curl -X POST \
  https://stage-api.wepay.com/legal_entities \
  -H 'Api-Version: 3.0' \
  -H 'App-Id: app-12345' \
  -H 'App-Token: app-token-12345' \
  -H 'Content-Type: application/json' \
  -d '{
  "country": "US",
  "token": {
    "id": "legal_entities-91af0e49-000e-4684-a7b9-a2deba006971",
    "permissioned_fields": [
      "controller.date_of_birth",
      "controller.country_info.US.social_security_number"
    ]
  }
}'

Tokenization Errors

When a token is expanded into your request, you may encounter a TOKEN_CONFLICT error code. These errors can be thrown if:

  • One of the fields in the token is also modified by the server request (reason code: TOKEN_FIELD_CONFLICTS_WITH_PROVIDED_FIELD). Resolve this by either omitting the field or sending the exact value that already exists on the token.
  • The token modifies fields that are not supplied in the permissioned fields list. This will only happen if permissioned_fields is provided and the token modifies data that is not included in that list.

Visit our Errors page for more details.


Your platform must provide users the ability to upload documentation. The user interface you create will support a variety of purposes, like uploading documentation to challenge a dispute or to verify personal or business information.

The WePay JavaScript library supports document creation so your platform can upload documents from a user’s browser while tokenizing that information, much like payment data.

Visit the Tokenization page for more details on tokenization.


Create a user interface

Create an interface for your users to upload documents with WePay.document.create. Embed the WePay JavaScript into a simple HTML page and use WePay.documents.create to tokenize the document. For example:

Note that the document types made available should be specific to Verifications or Disputes, depending on the context of the upload.


Submit documents

Once the documents are tokenized using the JS, document IDs will be returned looking something like b331ef99-9ee2-4910-8794-52a66ca3f3e0.

Important: Documents have a time-to-live (TTL) of 24 hours, after which, document's ID will become invalid, and the merchant will have to re-upload their documentation.

Following the example of Legal Entity document upload, use those IDs in a POST /legal_entities/id/verifications request to submit the documents to the Legal Entity:

Copy
Copied
curl -X POST \
  --url 'https://api.wepay.com/legal_entities/id/verifications' \
  -H 'Accept: application/json'\
  -H 'App-Id: {your-app-id}'\
  -H 'App-Token: {your-app-token}'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "controller": {
    "personal_verification": {
      "documents": [
        "724ec0d3-2eb5-461e-b72d-a15c6b1a9970",
        "3838d4ba-f497-4b6f-8d22-19b90cec4f23",
        "242f9ec7-a309-412c-976d-cc84074a508a"
      ]
    }
  }
}'

If documents are being uploaded in response to a Dispute, tokenize all documents and then send all the document IDs in a single POST /disputes/id request:

Copy
Copied
curl -X POST \
  --url 'https://api.wepay.com/disputes/id' \
  -H 'Accept: application/json'\
  -H 'App-Id: {your-app-id}'\
  -H 'App-Token: {your-app-token}'\
  -H 'Api-Version: 3.0' \
  -H 'Content-type: application/json' \
  --data-raw '{
  "documentation": {
    "documents": [
      "724ec0d3-2eb5-461e-b72d-a15c6b1a9970",
      "3838d4ba-f497-4b6f-8d22-19b90cec4f23"
    ],
    "explanation": "lorem ipsum dolores umbridge"
  }
}'

Note: Only 5 documents may be uploaded for any given dispute.


File types

The following file types are accepted:

  • .jpg
  • .jpeg
  • .png
  • .pdf

The file size limit is 10MB and multiple files cannot be uploaded using one request/call. Additionally, please ensure a file exists before a user uploads a document (a null file object cannot be uploaded).


Acceptable documentation to verify Merchant IC+ fee disclosure

The following documents can be uploaded to verify Merchant IC+ Fee Disclosure. WePay will pass these documents to the proper financial entities in charge of the decision-making process.

  • fee_disclosure

Acceptable documentation to challenge a dispute

The following documents can be uploaded to challenge a dispute. WePay will pass these documents to the proper financial entities in charge of the decision-making process.

  • cancelation_request
  • charge_back
  • contract
  • correspondence
  • item_description
  • itemized_receipt
  • invoice
  • ip_logins
  • proof_of_credit
  • return_policy
  • refund_policy
  • signed_contract
  • tracking
  • written_rebuttal

Acceptable documentation to verify a legal entity

The following is a comprehensive list of documents that can be uploaded to help WePay verify a legal entity:

  • affiliation
  • alberta_province
  • any_other_government_issued_photo_id
  • articles_amendment
  • advise_and_consult_responses
  • articles_of_association
  • banking_license
  • bankruptcy_trustee
  • benefits_card
  • birth_certificate
  • building_society_statement
  • business_license_certificate
  • business_report
  • canadian_citizenship
  • canadian_health_card
  • certificate_of_association
  • certificate_of_authority
  • certificate_of_domestication
  • certificate_of_existence
  • certificate_of_formation
  • certificate_of_good_standing
  • certificate_of_incorporation
  • certificate_of_liability_insurance
  • certificate_of_limited_partnership
  • certificate_of_naturalization
  • certificate_of_organization
  • certificate_of_status
  • certificate_of_trust
  • certification_of_compliance
  • certified_copy_of_court_order
  • certificate_of_citizenship
  • certificate_of_naturalization
  • change_of_address
  • charity_license
  • charity_registration_number
  • companies_house
  • corporate_amalgamation_agreement
  • corporate_annual_gov_filing
  • corporate_profile_report
  • council_tax_statement
  • credit_card_statement
  • current_bank_statement
  • current_local_tax_bill
  • current_lease_contract
  • current_utility_bill
  • current_business_lease_contract
  • current_residence_lease_contract
  • dba_registration
  • divorce_decree
  • drivers_license
  • electoral_register_entry
  • employment_authorization_card
  • evidence_of_authority
  • evidence_of_corporate_registration
  • evidence_of_exchange
  • evidence_of_name_change
  • evidence_of_nonprofit_registration
  • evidence_of_registration_of_regulated_funds
  • executor_of_estate
  • filed_audited_accounts
  • firearms_certificate
  • foreign_passport
  • form_adv
  • hoa_statement
  • hud_statement
  • identity_card_northern_ireland
  • identity_card_by_eoni
  • inland_revenue_tax_assessment
  • insurance_bill
  • insurance_card
  • insurance_declaration_page
  • irs_501c3_determination
  • irs_confirmation_of_tin
  • letter_from_social_security
  • limited_partnership_certificate
  • limited_partnership_charter_letter
  • llc_agreement
  • llc_filing_receipt
  • marriage_certificate
  • matricula_consular_card
  • military_id
  • military_orders
  • miscellaneous_charge_network_compliance_doc
  • miscellaneous_compliance_doc
  • mortgage_closing_document
  • mortgage_statement
  • other_evidence_of_filings
  • other_government_issued_photo_id
  • operating_agreement
  • order_of_creation
  • passport
  • partnership_agreement
  • proof_of_supervision_by_gov
  • social_security_card
  • permanent_resident_card
  • secretary_of_state
  • schedule_q
  • social_insurance_number_card
  • social_security_benefit_notice
  • social_security_card
  • state_registrar_of_legal_entities
  • tax_exemption_letter
  • tax_statement
  • tribal_or_bureau_of_indian_affairs_id
  • trust_agreement
  • vehicle_registration
  • web_referral
  • quebec_company_registration

Acceptable documentation for account fraud protection

The following documents can be uploaded for account fraud protection. WePay will pass these documents to the proper financial entities in charge of the decision-making process.

  • contracting_license_or_insurance_document
  • articles_of_incorporation
  • business_tax_document
  • merchant_processing_statement
  • vendor_contract_agreement
  • insurance_document
  • proof_of_registration
  • government_id
  • bank_statement
  • invoice_outreach

These only need to be uploaded if WePay specifically requests documentation. The types of documents that users need to provide will depend on the entity's legal_form and country:

Individual, US

These apply to verifications for controller and additional_representatives in the United states:

Document descriptionDocument type
Driver’s License with photodrivers_license
State or Government Issued ID with photoother_government_issued_photo_id
Passport or Passport Card with photopassport
US Military/Veteran's ID with photoother_government_issued_photo_id
Tribal or Bureau of Indian Affairs with photoother_government_issued_photo_id
Permanent Resident Card with photo (also known as the Green Card or Resident Alien)permanent_resident_card
Foreign Passport (non-US citizen, Beneficial Owner Only)passport
US Birth Certificatebirth_certificate
Social Security Cardsocial_security_card
Utility bill bearing the name and address used for opening the account including: Electric, Gas, Water, Phone, Cable, Alarm, HOA.current_utility_bill
Statements including: Bank Statements, Credit Card Statements, Property Tax Bill, HUD Statement, Mortgage, HOA.current_bank_statement
Rental/Lease contract for current residence bearing the name and address used for the opening account.current_lease_contract
Certificate of Citizenshipcertificate_of_citizenship
Certificate of Naturalizationcertificate_of_naturalization
Certified Copy of Court Order (must contain full name and date of birth)certified_copy_of_court_order
Employment Authorization Card (with photo) issued by a U.S. federal government agency.employment_authorization_card
Benefits (e.g. welfare services) card with photobenefits_card

Individual, CA

These apply to verifications for controller and additional_representatives in Canada:

Document descriptionDocument type
Driver’s License with photodrivers_license
Passport with photopassport
Certificate of Canadian Citizenship (paper document or card but not a commemorative issue)certificate_of_citizenship
Permanent Resident Card with photopermanent_resident_card
Canadian Health Cardbenefits_card
Canada Birth Certificatebirth_certificate
Social Insurance Number Cardsocial_insurance_number_card
Utility bill bearing the name and address used for opening the account including: Electric, Gas, Water, Phone, Cable, Alarm, HOA.current_utility_bill
Statements including: Bank Statements, Credit Card Statements, Property Tax Bill, HUD Statement, Mortgage, HOA.current_bank_statement
Rental/Lease contract for current residence bearing the name and address used for the opening account.current_lease_contract

Entity, US

These apply to verifications for entity in the United States:

Document descriptionDocument type
Articles of Incorporation / Certificate of Incorporationevidence_of_corporate_registration
Articles of Organization / Certificate of Organizationevidence_of_corporate_registration
DBA Registration/Assumed Name Certificateevidence_of_corporate_registration
Partnership Agreement (LLP, LP)evidence_of_corporate_registration
Trust Agreement and Amendmentevidence_of_corporate_registration
Articles of Amendment/Restated (Designation/Merger)evidence_of_corporate_registration
IRS 501(c) (3) determination letterevidence_of_corporate_registration
Business License (Sole Proprietorship)evidence_of_corporate_registration
Certificate of Associationevidence_of_corporate_registration
Certificate of Authorityevidence_of_corporate_registration
Certificate of Domestication/Certificate of -Corporate Domestication (Delaware only)evidence_of_corporate_registration
Certificate of Existenceevidence_of_corporate_registration
Certificate of Formation (for US only, Limited Liability Company (LLC))evidence_of_corporate_registration
Certificate of Formation (Texas)evidence_of_corporate_registration
Certificate of Good Standing (Current)evidence_of_corporate_registration
Certificate of Incorporationevidence_of_corporate_registration
Certificate of Limited Partnership (LP)evidence_of_corporate_registration
Certificate of Organizationevidence_of_corporate_registration
Certificate of Trustevidence_of_corporate_registration
Exemption (tax) Letter (by State or IRS)evidence_of_corporate_registration
Utility bill bearing the name and address used for opening the account including: Electric, Gas, Water, Phone, Cable, Alarm, HOA.current_utility_bill
Statements including: Bank Statements, Credit Card Statements, Property Tax Bill, HUD Statement, Mortgage, HOA.current_bank_statement
Rental/Lease contract for current residence bearing the name and address used for the opening accountcurrent_lease_contract
Schedule Q Form 5300evidence_of_corporate_registration
IRS Confirmation of TINevidence_of_corporate_registration

Entity, CA

These apply to verifications for entity in Canada:

Document descriptionDocument type
Certificate of Status / Certificate of Good Standing / Certificate of Compliance / Certificate of Existenceevidence_of_corporate_registration
Articles of Incorporation / Articles of Associationevidence_of_corporate_registration
Utility bill bearing the name and address used for opening the account including: Electric, Gas, Water, Phone, Cable, Alarm, HOA.current_utility_bill
Statements including: Bank Statements, Credit Card Statements, Property Tax Bill, HUD Statement, Mortgage, HOAcurrent_bank_statement
Rental/Lease contract for business bearing the name and address used for the opening account.current_lease_contract