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

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

We recommend using an aliased email address to sign up (something like payments@your-company.com) 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.

Confirm Email Address

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

Generate App Tokens

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.

Stage vs. Production

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:

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

Next, identify the country your business is located in:

App entity country location

Then, identify the entity type of your application:

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

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

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.

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.

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

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.

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": "facebook.com.merchantblob"
  },
  "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 'https://stage-api.wepay.com/accounts/D3f61e56-5d99-4895-af2d-a07ab48476e9' \
  -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

All API calls require the below headers:

• POST /legal_entities
• POST /legal_entities/{id}
• POST /accounts -- When the payout structure is being sent
• POST /accounts/{id} -- When the payout structure is being sent
• POST /payment_methods

API Header Responses

API Versions

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.

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.

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.

{
	"error_code": "NOT_AUTHORIZED",
	"error_message": "FEATURE_NOT_ENABLED_FOR_APPLICATION"
}

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

Idempotency

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.

Using Magic Headers

Errors

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

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

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

Handle 400s

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

Custom Data is available on all API resources, except:

• rBits
• Orders
• Items

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: