JavaScript Library

Access the Javascript libraries below:

• Minified
• Full

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 we require Risk headers:

Risk Headers

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

Tokenization

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

In addition to reducing PCI compliance overhead, 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:

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.

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

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

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

<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>

WePay.configure

WePay.tokens.create

{
    "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.

<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. We take token data and combine 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.

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"
  }
}'

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

• 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.

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.

Document Upload

Create a user interface

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

Submit documents

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.

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:

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. We 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. We will pass these documents to the proper financial entities in charge of the decision-making process.

• 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

To verify a Legal Entity, we recommend requesting government-issued documentation showing address and name, such as the following:

• EIN Assignment Letter
• Sales Tax Documents
• Liquor License
• Government issued bills (I.e, city water or trash bill)

The following is a comprehensive list of document types accepted by our JavaScript library, all of which might not be acceptable to manually 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
• certification_of_compliance
• certified_copy_of_court_order
• certificate_of_citizenship
• certificate_of_naturalization
• change_of_address
• charity_license
• charity_registration_number
• corporate_annual_gov_filing
• council_tax_statement
• current_local_tax_bill
• current_utility_bill
• 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
• filed_audited_accounts
• firearms_certificate
• foreign_passport
• identity_card_northern_ireland
• identity_card_by_eoni
• inland_revenue_tax_assessment
• irs_501c3_determination
• irs_confirmation_of_tin
• letter_from_social_security
• limited_partnership_certificate
• llc_filing_receipt
• marriage_certificate
• matricula_consular_card
• military_id
• military_orders
• miscellaneous_compliance_doc
• other_evidence_of_filings
• other_government_issued_photo_id
• order_of_creation
• passport
• 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
• vehicle_registration
• quebec_company_registration

Acceptable documentation for account fraud protection

The following documents can be uploaded for account fraud protection. We 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

Individual, US

Individual, CA

Entity, US

Entity, CA