Get Started


Review Supported Platforms

Before getting started, verify that we support your platform type:

  1. Small-Medium Business (SMB)
  2. E-commerce
  3. Point of Sale
We do not support platforms whose primary user base consists of merchants participating in any of the prohibited activities per our US merchant Terms of Service and CA merchant Terms of Service.
Click to view all prohibited activitiesNote: Merchants in the United States from this list and merchants in Canada from this list cannot process with WePay, and thus must not be onboarded.

AdultAdult sites, content, sexual services, child pornography, bestiality, escort services, mail order brides
Dating services
Massage parlors
AggregationPayment facilitator to other merchants
AuctionsInternet auction, bidding fee auction, penny auction
Cash, stored value, virtual currencyCash or cash equivalent, purchase of gold, silver, platinum, palladium, bullion and/or bars (collectibles are not prohibited)
Cash disbursement
Digital Wallet, stored value, prepaid companies, prepaid phone cards or phone services, sale of mobile minutes, or quasi cash
Virtual currency or credits that can be monetized, re-sold or converted to physical or digital goods or services or otherwise exit the virtual world
DebtBail bond services or bankruptcy lawyers
Credit counseling or repair services; debt elimination, consolidation or reduction services; factoring or liquidators
Damages, losses, penalties, or fines of any kind; alimony, child support, or other court-ordered payments
Debt collection; payment for a dishonored check or for an item deemed uncollectible by another merchant
High interest rate non-bank consumer lending, including payday lending and title loans
Loan payments transacted on a credit card
DrugDrugs or drug paraphernalia
Marijuana dispensaries and related products or services
Personal enhancement products or nutraceuticals - vitamins, supplements, herbals, weight loss programs
Pharmaceuticals, internet pharmacies
Pseudo pharmaceuticals
EducationFor profit higher education
Electric car chargingElectric car charging
Financial servicesBanks, credit unions, savings and loan associates, unit trusts, mutual funds, foreign exchange, Bureau de Change
Buy here, pay here (in-house financing)
Cash advances
Currency exchanges or dealers
Money transfer, wire transfers, money orders, money transmitters, and check cashing, including merchants required to be registered as money services businesses
Payable through accounts (foreign or domestic)
P2P payments
Gambling, lotteryGambling or betting, including lottery tickets, casino gaming chips, off-track betting, sports forecasting or odds making, fantasy sports, memberships on gambling-related internet sites (including unlawful Internet gambling as defined in 12 C.F.R. Section 232.2(bb)) and wagers at races, contests, sweepstakes, raffles, and offering prizes as an inducement to purchase goods or services
GovernmentPostal Services
High RiskAstrology and related prediction or forecasting services
Brand damaging
Career placement or advice center merchants
Cyberlockers, file sharing, file storage
Delayed delivery merchants where the good or service is not shipped, delivered, or fulfilled when the card transaction is processed but is to occur at a future date
International card sales greater than 20% of total sales
Lifetime guarantee
Merchants who are known to test or conduct research on animals
Merchants who are known to have labor/working condition issues
Merchants who are involved in developments that involve land acquisition and involuntary resettlement
Merchants who are known to have experienced material community issues (e.g., demonstrations, blockades, security threats)
Merchants whose proceeds may have the potential to impact indigenous peoples
Merchants who have been subject to allegation and impacts related to human rights violations
Money back guarantees exceeding 30 days
Motor vehicle sales
Online help for classes, homework or assignments
Online personal computer technical support
Pawn shop
Private prison operators
Psychic services
Sale of airline, hotel, rental, or other miles or points
Sale of products or services identified by government agencies to have a high likelihood of being fraudulent
Sale of social media activity
Sale or exchange of animals and regulated items such as animal pelts
Shipping or forwarding brokers
IllegalCounterfeit or possibly counterfeit goods, or products that infringe on the intellectual property rights of others
Deceptive, unfair, or predatory practices
Forced child labor/human trafficking, slavery
Hate, violence, racial intolerance, terrorism, the financial exploitation of a crime, or items or activities that encourage, promote, facilitate, or instruct others regarding the same
Unlawful activities, illegal substances or products, or items that encourage, promote, facilitate, or instruct others regarding the same
Investment, real estateCommodity trading or security trading; equities (including stocks, bonds, or any other ownership position in a corporation)
Crowdsourced fundraising for stock or equity
Distressed property sales and marketing; real estate flipping
Goods or services to be delivered more than four (4) months in the future, with an intention of gaining return on investment
Mortgage accelerator processors
Timeshares, timeshare resales, and related marketing
MarketingBuyers clubs, membership clubs
Direct marketing - inbound telemarketing
Direct marketing - negative option, renewal, or continuity subscription practices
Direct marketing - travel-related arrangement services
Discount coupon merchants or online sites
Discount medical or dental plans, including discount insurance
Door to door sales
Infomercial merchants
Lead generation businesses
Lifetime payments for timeshares, guarantees, and the like
Marketing activities involving "pay only for shipping" and/or "free trial" periods
Outbound telemarketers and telecom merchants
Rebate or upsell merchants
MilitiaCross border military related goods
Militia, armed groups or armed gangs
Political partiesConsulates, embassies, missions to the United Nations
Political organizations
RegulatedAge restricted products or services, such as alcohol
Firearms, including ammunition
Other weapons that are not related to firearms
Tobacco, cigarettes, e-cigarettes
TelecommTelecommunications, including wireless, cable, satellite, wireline, and ISP
TravelAirlines, including charter air carriers
Steamships and Cruise lines
Travel agencies or tour operators
Travel industry, including car rental and lodging

Our API products are packed full of features and conveniences to help you handle different scenarios, like reducing PCI scope, preventing double charges in case of error, and adding in your own custom data to help maintain things like state.

By the end of this doc, you'll have the right information to build an API call.

Sign Up

Start by heading over to

We recommend using an aliased email address to sign up (something like as this allows for multiple people to access your company's account, instead of tying it to a single person's login. This also allows the person responsible for filling in Know Your Customer (KYC) details to do so at a later time while you onboard to the API and begin making calls.

If you're simply testing the API, it's fine to use your own email address, and create a separate account using an alias at a later time.

Contact our Sales team to confirm the ability of your platform to obtain Production access.

Confirm Email Address

Make sure to confirm your email address once you've finished signing up for an account. If you haven't, be sure to visit here, and click the banner to resend the confirmation email.A banner reminding you to confirm your email
A banner reminding you to confirm your email

Sign In

Once sign up has been completed, log in to your account with your confirmed email.

The first screen you will see is set to the Staging environment, and before you can start testing the API, you will need to generate your App Token.

Main App screen
Main App screen

Generate App Tokens

Before you can make an API call, you'll need to grab your App ID, API version, and App Token. You'll need to generate an App Token through the Partner Center. Simply click “Create Token”, enter a unique name, and hit save.

Note that the Legal Entity and Account IDs displayed with your API credentials are specific to your platform; each merchant will require their own Legal Entity and Account.

You can generate up to three tokens, though it is not necessary to generate more than one token. As an example for using multiple tokens, you can think of each as a way to logically separate different components of your system which may interface with different parts of the Clear API. For example, you could have one service that exclusively deals with payment processing, which would have its own token that is revocable at any time.


As a security precaution, rotate your App Tokens every 3 months by visiting the Partner Center. Delete your current tokens, create new tokens, and replace your old tokens with your new ones.

Stage vs. Production

Base URLEnvironment
When you finish signing up for an account, you'll begin in the stage environment. Your API credentials will let you make API requests to the base URL, appended with an endpoint. The stage environment is intended for use in the development and prototyping of your application.

In order to process payments in Production, you must first be assigned an integration manager. If you are not managed and would like to move to Production, contact our Sales team to move further. We suggest completing this step first to align on integration requirements.

When you are managed and ready to launch, you can begin the process of certification to migrate to the Production environment in the dashboard.

As using production credentials executes actual money movement, we do not allow any account to migrate to the production environment until they have passed certification. We define certification throughout the basic integration process. In addition, you're required to submit personal and business details before you can access the production environment.

Submit Personal and Business Details

To submit personal and business details, change context to Production in Partner Center:


Your progress cannot be saved, so please have all necessary information accessible

Submit your personal and business KYC in the Production Context

Click the blue "Update your personal information" button in the Production context to begin entering your data:

Submit your personal and business information in the Production Context
Submit your personal and business information in the Production Context

Next, identify the country your business is located in:

App entity country location
App entity country location

Then, identify the entity type of your application:

App Entity Type
App Entity Type

If your application is a business, specify whether your business is a corporation, LLC, or partnership. If your application is a nonprofit, specify whether your nonprofit is a nonprofit corporation or an unincorporated association.

Identify your application's industry category and type to help us identify an appropriate merchant category code for your account.

Next, fill in your application's business details:

App business details
App business details

Next, supply personal details for a controller of your application's business:

App personal details
App personal details

A controller is a single individual with significant responsibility to control, manage, or direct a legal entity customer, including an executive officer or senior manager (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer); or any other individual who regularly performs similar functions (e.g., the control prong). This list of positions is illustrative, not exclusive, as there is significant diversity in how legal entities are structured.

Visit our Partner Center guide to learn about the other business management features and functionalities the Partner Center has to offer.

Subscribe To API Notifications

Notifications are webhooks sent by the API to deliver information about your merchants, payment processing, and payment operations.

The lifecycle follows this general pattern:

  1. Receive a notification from WePay about a payment, merchant, payout, or other operation.
  2. Inspect content of the Notification Signature to ensure that the notification is intact and sent from us, as opposed to a malicious actor.
  3. Inspect payload.create_time to determine chronology, not the event_time of the notification itself

If a Notification fails to reach your servers, we will attempt to retry following this pattern:

  • 1st retry will happen 15 minutes after the initial attempt.
  • 2nd retry will happen 30 minutes after the 1st retry.
  • 3rd retry will happen 1 hour after the 2nd retry.
  • 4th retry will happen 6 hours after the 3rd retry.
  • 5th retry will happen 12 hours after the 4th retry.
  • 6th retry will happen 24 hours after the 5th retry.
We define "failing to reach your servers" as receiving any HTTP code other than 200 or 201. This also includes network retries. Due to potential retries, it is important to use the event_time value rather than receipt time to identify the order in which events occur.

When you transition to production on your dashboard, our team will validate your Notifications implementation. Notifications are not stored permanently. If you haven't subscribed to notifications, you won't be able to retrieve older notifications once subscribed. However, once subscribed, Notifications are stored for 30 days.

Subscribe to API Notifications by making a POST /notification_preferences API request.

Recommended API Notification Subscriptions:

  • accounts.created
  • accounts.capabilities.updated
  • payouts.failed
  • disputes.created
  • disputes.resolved
  • legal_entities.verifications.updated
  • payments.completed
  • payments.canceled
  • payments.failed
The custom_data parameter may not appear in the notification payload for any given notification topic. To lookup the custom_data parameter for a specific notification, send an API request with the resource ID to the endpoint you would like to access.

Supply Risk Information

As a platform, it's extremely important to make sure you're providing us with Risk information about your merchants, payers, and transactions.

We have a team of Risk Analysts, plus machine learning models to capture data and ensure fraud is handled correctly. By feeding more data to the system, your platform and merchants have a better chance of minimizing losses and continuing a smooth user experience. Conceptually, we think of Risk as structured meta data you can add to almost every resource on Link except Transaction Records and Recoveries. You either can pass risk bits (rBits) by including them inline with a resource (like Payments), or through a 2-step process by calling the rBits endpoint directly with the associated resource ID (like Accounts).

If required by our team, you may need to send Items and Orders in addition to rBits, to augment your risk data. By providing this data, you'll provide our Risk team with richer data to continue leveraging our sophisticated risk algorithms, and ultimately better protect you and your merchants.

Refer to the Risk Certification to identify standard required rBits, and work with your WePay integration team to be sure there are no custom modifications that we may require.

Add Rbits

We'll first walk through the inline flow. When processing payments, all API calls accept an array of rBits that you can define inline.

For example, let's say you want to attach the Transaction Details object to your Payments. You've noticed a significant increase in payments, of which a bunch were spam. As such, you now add in Transaction Details as an rBit to get ahead of the problem.

  "rbits": [{
    "receive_time": 1367958263,
    "type": "transaction_details",
    "source": "user",
    "transaction_details": {
      "itemized_receipt": [
    	"amount": 105,
    	"currency": "USD",
    	"description": "Premium lawn service package",
    	"item_price": "100",
    	"project_name": "Lawn service at 123 Fake St.",
    	"quantity": 1,
    	"service_billing_method": "hourly_billing_at_project_rate"
      "note": "returning customer, new payment method"

You'll notice that at creation time of a new Payment, an rBit array was included. If you choose to do so, you can pack more rBits into the array.

It's not necessary to do the inline flow, as you can first create a Payment and update it with rBits after creation.

Next, we'll walk through the 2-step flow.

For example, let's say you're onboarding merchants and you define rBits after onboarding. You want to attach the External Account object to merchant Accounts. Once you receive an Account ID from us, you create an rBit by sending a POST /rbits request like this:

  "address": {
    "account_type": "facebook",
    "connections": "2000",
    "create_time": 1235635140,
    "feedback_score_percent_positive": 0.87,
    "feedback_scores_provided": "476",
    "is_partner_account": false,
    "uri": ""
  "associated_resource": {
    "id": "{merchant-account-id}", // insert the merchant's account ID here
    "resource": "accounts"
  "receive_time": 1367958263,
  "source": "guidestar",
  "type": "address"

View the full API reference to see where you can add rBits. In general, the more you add to your Accounts and Payments, the better overall experience and minimization of loss for your end merchants and payers.

Resource IDs

Resource IDs returned by our APIs are case-sensitive. For instance, if the following is returned by us as an Account ID:

  • d3f61e56-5d99-4895-af2d-a07ab48476e9

And you can later lookup that same account by making a GET request, even with just one letter in the wrong case:

curl -X GET \
  --url '' \
  -H 'Accept: application/json'\
  -H 'App-Id: XX'\
  -H 'App-Token: {}'\
  -H 'Api-Version: 3.0'

The account you are attempting to lookup will not be returned.

API Headers

A set of headers are required for all API calls, and certain endpoints conditionally require more. As a reminder, access API credentials here.

All API calls require the below headers:

Header KeyHeader Value (example)
POST calls to the /payments and /refunds endpoints require "Unique-Key". The value for Unique-Key is defined by you, and we outline strategies in the below Idempotency section.Finally, send Client-IP and WePay-Risk-Token if you are not using the WePay Helper JS Library for the following endpoints:

API Header Responses

Our response headers will contain an X-Correlation-Id. At a minimum, it should be stored for each /payments and /refunds request, though storing the correlation ID for requests to every endpoint is recommended. These IDs will help with debugging should the need arise.

API Versions

When interfacing with the WePay API, you select which API version to use by passing it in the Api-Version request header. API versions are compatible with other versions, so you could make a call to certain endpoints using v3.1, and to others as v3.0.

If you do not need to use different versions, it's completely fine to use a single version. The latest version is 3.0.

API Rate Limits

By default, the API rate limit is 30 requests per endpoint and per account every 10 seconds on a sliding window.

The endpoint API rate limit ensures that if a single service (like creating payments with POST /payments) sees a spike, then other services will not be impacted (such as finding accounts with GET /accounts).

The account API rate limit ensures that if a single merchant's Account ID sees a spike in POST /payments requests, other merchants' ability to create payments will not be impacted. Note that this rate limit is specific to the /payments endpoint.

The rate limit is calculated using the sliding window algorithm, meaning that API requests are measured on a rolling basis. If the limit is exceeded, an API error will return and the details will indicate which throttle (endpoint or account) was activated.


If your app attempts to send a total of 31 requests to a single endpoint in a sampling period of 10 seconds, then the last request in chronological order will receive the THROTTLE_EXCEEDED API error. If 31 requests were sent in the first second, you will be able to successfully send new requests at 11 seconds. On the other hand, if 15 requests were sent on second 9, and 16 requests were attempted on second 10 (1 would be throttled on second 10), you will then be able to send 15 un-throttled requests on second 19 (once second 9 is no longer included in the sliding window), and another 15 on second 20.

As another example, say your app hit the same endpoint with 3 requests per second for seconds 1-9, and then sent 4 requests on second 10. The last request to come in would receive an error, and you would be able to send another successful request on second 11.

If you have a business use case that requires a higher rate limit, please speak to your account manager or API Support, at

Default Permissions

When you register for API credentials with us, your credentials will have access to pre-built components and Default Permissions automatically. In order to get additional permissions for custom components, work with your WePay integration team.

Sending calls to endpoints or with parameters which are not included in the default permissions will result in the following error:
	"error_code": "NOT_AUTHORIZED",
During your planning, take note of each feature you'd like access to and submit a request to your account manager, technical account manager, or our developer support ( Your request should include:
  • Your platform's stage app-id
  • A high-level description of your business
  • Your business use case for the specific feature(s) being requested

If you want to use any features with Gated Permissions, be sure to work with your WePay integration team to get access. Keep in mind that Gated Permission features may have prerequisites or other requirements that you must meet.

Default PermissionsGated Permissions
Legal Entities
Payouts & Payout Methods
Payment Methods
POST /payment_methods with any of the following paramters:
POST /payments with any of the following parameters:
Refunds, Disputes, Adjustments, & Recoveries
Transaction Records and Billing Statements
Orders, Items, and rBits
Terminals and Session Tokens
Notifications and Notification Preferences


Making GET calls will not modify resources, and sending a POST to an endpoint will update the fields provided in the POST body only. If you'd like to delete a field in an object, send a POST with the field set to NULL. For complex objects, like beneficial owners-- where you may not have all data at once--pass an empty object, like . This lets you progressively update the Legal Entity object.

In error scenarios, retrying a payment and refund can lead to overcharging a payee or drawing too much from a merchant. In order to safeguard against these scenarios, you will use the "Unique-Key" key and unique value (generated by you) in the request header. You can use any value for the Unique Key, as long as it's unique. After a request with a Unique-Key has finished processing, subsequent duplicate requests (where JSON body, parameters, headers, and all their values are exactly the same) will simply fetch the created resource. The Unique-Key error only comes into play while the initial Unique-Key is still in use. A Unique-Key is considered still in-use when the API request it was initially used on is still being processed and we have not responded. We limit this timeframe to 30 seconds, and will return a timeout error if we are unable to provide a response in that timeframe.

As an example, let's say your platform handles rent between landlords and tenants. A good unique key could be the tenant's payment date, so that double payments do not occur.

For all POST calls made to /payments and /refunds, you are required to send "Unique-Key" in the header. The Unique-Key requirement makes these POST requests idempotent and safe, nullifying duplicate successful requests. For all other POST calls, the Unique-Key is optional. In general, a Unique-Key is valid for 24 hours.For more information on error handling and retry strategies, see the Design A Retry Strategy cookbook.

Using Magic Headers

Magic header values trigger a given behavior by including a magic value for the WePay-Magic-Behavior key in the call header. These calls will return static responses, regardless of the API request body that you send, and are intended to provide the full structure of a response under certain circumstances for you to model additional testing and development against.

Making idempotent POST/ payments requests to test your application is made easy with the use of Idempotency_Downtime_xxx and Idempotency_Retry_xxx as Magic Headers. Idempotency_Retry_xxx will delay the next xxx requests by returning simulated 500 errors. Requests sent with this unique key, Idempotency_Downtime_xxx, will return simulated 500 errors over the next xxx seconds. Notes, that you are responsible for defining xxx with the amount of requests or seconds you'd like the Magic Header to effect.


Our API follows standard API conventions with errors. You can view the API reference documentation for an exhaustive list of error codes. Throughout the integration guide, we will also highlight special errors and remediation strategies.

Avoid Hanging API Requests

Our API services will timeout after 30 seconds if no response is returned within that timeframe. It is recommended that you adjust your timeout settings to reflect this, in the case that your API request takes a little longer to process.

Handle 500s

In general, 500 HTTP errors indicate that an unknown error occurred and are safe to implement your retry logic for. See Design A Retry Strategy to create the best retry logic for your particular integration.

Note that 503 errors indicate that a known issue caused the error, but that the request can be retried at a later time.

In the case of a 500 returned on /payments or /refunds, you will need to implement proper retry logic, depending on a Card Present (CP) or Card Not Present (CNP) transaction flow.

Card Not Present Transactions

In general, you should implement a back-off strategy upon receiving the first 5xx error code (like an exponential back-off). If a 5xx HTTP error returns for a request with a unique key the first time, resend the request with the same unique key, and carry on until you reach the threshold for your exponential back-off window (or the payment succeeds with a non 5xx error code).

If you use a different unique-key during your back-off, you run the risk of double-authenticating a payment. If you receive the API Error Code CONCURRENT_UNIQUE_KEY_REQUEST_IS_PROCESSING, you can keep retrying safely.

If you reach the end of your retry window for back-off, grab the correlation-ID in the response header, and escalate the payment issue to WePay.

Card Present Transactions

Like CNP transactions, in general, you should implement some type of back-off strategy when handling 5xxs. With CP transactions, however, a successful authentication at the terminal is sufficient to let a payer walk away from the terminal. Put another way, if you receive an encoded_payment_method, an authentication has happened and you can attempt to execute a payment with the same error handling as the above Card Not Present section.

Handle 400s

If a 4xx HTTP error returns for a request with a unique key, that Payment cannot be processed. This means that new information must be submitted by the user, and a new unique key should be used on the new request. Refer to error code documentation here for further information on error responses.

Custom Data

Custom data refers to a key-value object that can be passed in most API calls. The point of custom data is to add any additional metadata you need to store for resources that you can't store using predefined fields. There is a limit of 10kb for custom data objects.

As an example, let's say you wanted to create a Payment resource, and wanted to store the payer's user name on your platform in the Payment API object. You could add a key value pair to custom data, like so:

"custom_data": {
    "merchant_username": "merchant1"
And any time you retrieve or update this payment, the custom data will be stored and returned. Custom data is a JSON object, and allows for nesting. The API will not overwrite custom data, and will append new keys/values. If you'd like to remove keys and values, assign existing keys to null, or to remove the keys, set custom_data to null and re-add data. Do not send personally identifiable information (PII) through custom data.

Custom Data is available on all API resources, except:

  • rBits
  • Orders
  • Items
custom_data may not appear in the notification payload for any given notification event topic. To lookup the custom_data parameter for a specific notification, send an API request with the resource ID to the endpoint you would like to access.

Handle Communications

We will handle a majority of the communications to your end users. One exception is micro deposit emails for manually verified bank account payment methods.

Despite that, it is beneficial to subscribe to Notifications just to be aware of what communication is being sent to Merchants and payers on your platforms. When deciding which notifications to subscribe to, it is important to note that implementing Notification Signatures ensures a higher level of security by validating that all notifications are coming from us.

Below are recommended Notification event topics to subscribe to related to end user email communications:

ScenarioNotification Event Topic(s)
Complete onboarding
  • accounts.created
  • accounts.capabilities.updated
Disabled Account Capabilitiesaccounts.capabilities.updated
Invalidated Payout Method
  • payouts.failed
  • accounts.capabilities.updated
New Disputedisputes.created
Resolved Disputedisputes.resolved
Legal Entity details require an updatelegal_entities.verifications.updated
Supporting documentation is required for Legal Entity Verificationslegal_entities.verifications.updated
Payment receiptpayments.completed
Canceled Paymentpayments.canceled
Failed Paymentpayments.failed
Failed Payoutpayouts.failed